API Authentication
The Para API offers a few options for authentication. Para API clients can call the API authenticated either as users or apps:
| Principal | Method | Credentials | Access |
|---|---|---|---|
| App | Signed request (AWS v4) | Access key and secret key | Full API access |
| App | App JWT | Signed with app’s secret key | Full API access |
| User | User JWT, also called a personal access token (PAT) | Signed with user’s secret + app secret | Restricted API access (see resource permissions) |
Use signed requests for server-side apps. A super JWT is an option for clients that cannot sign requests, but it requires the app secret key. A user JWT identifies an individual user and never grants app-level access. This auth method is suitable for insecure client-side code or mobile apps.
Signed requests
Section titled “Signed requests”Para uses the AWS Signature Version 4 algorithm to sign API requests. All Para client libraries use this method for API authentication.
A signed request includes the access key and is signed with the secret key. The secret key is never sent in the request. A request that is signed correctly has full access to the app API.
We recommend that you use one of our API client libraries to handle signing. See Para client libraries.
Full access with app JWTs (“super” tokens)
Section titled “Full access with app JWTs (“super” tokens)”A super JWT is a JSON Web Token (JWT) that authenticates an app, not a user. It has no user subject and gives full access to the app API. Para accepts it as a Bearer token.
The token must:
- use the
HS256algorithm - contain the
appidclaim - be signed with the app secret key
Only trusted clients should create super tokens. Do not put the app secret key in browser or mobile code. Generate the token on a server, or use a signed request instead.
To create a super token in JavaScript, use a JWT library such as jsrsasign:
function getJWT(appid, secret) { var now = Math.round(new Date().getTime() / 1000); var sClaim = JSON.stringify({ exp: now + (7 * 24 * 60 * 60), // expires at iat: now, // issued at nbf: now, // not valid before appid: appid // app id must be present }); var sHeader = JSON.stringify({'alg': 'HS256', 'typ': 'JWT'}); return KJUR.jws.JWS.sign(null, sHeader, sClaim, secret);}The example uses a seven-day expiry. Change it to match your security requirements.
Attach the token to every request:
Authorization: Bearer eyJhbGciOiVCJ9.eyJzdWIiOi0._MKAH6SGiKSoqgwmqUaxuMyEWhen you call the Para API from JavaScript in the browser, make sure you run a web server and not file:///, or your
browser might not allow CORS requests. Also check that CORS is enabled in Para with para.cors_enabled = true.
Changing the app’s secret key
Section titled “Changing the app’s secret key”Call POST /v1/_newkeys with a request signed by the current keys to generate a new secret key. The access key does not
change, and Para shows the new secret key only once.
Example: Calling the API from Postman or Insomnia
Section titled “Example: Calling the API from Postman or Insomnia”You can access the protected API from a REST client like Postman or Insomnia, since those two support the AWS Signature v4 algorithm, used in Para. Open up Postman and in the “Authorization” tab choose “AWS Signature”:
| Field | Description |
|---|---|
| Access Key | Your Para access key, e.g. app:myapp. |
| Secret Key | Your Para secret key. |
| Region | Always us-east-1. |
| Service Name | Always para. |
Make sure you don’t have extra headers in your requests because Postman is known to calculate invalid signatures for such requests.
User access
Section titled “User access”Users do not receive app keys. A user signs in through an identity provider, and Para returns a user JWT. This token is also called a personal access token (PAT). It grants restricted access to the user’s own objects and to resources allowed by the app’s resource permissions.
Get a user JWT
Section titled “Get a user JWT”Call POST /jwt_auth with the app ID, the provider, and the provider token:
POST /jwt_authContent-Type: application/json
{ "appid": "app:myapp", "provider": "password",}The response contains the JWT and the user object:
{ "jwt": { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires": 1450738414000, "refresh": 1450137214490 }, "user": { "id": "587408205806571520" }}Send the access token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...The token expires after 24 hours by default. You can change this with para.jwt_expires_after. Para client libraries
refresh the token automatically before it expires.
Example: User auth with the Java client
Section titled “Example: User auth with the Java client”The Para client handles sign-in, token storage, and token refresh:
User user = paraClient.signIn("facebook", "facebook_access_token");Supported providers are facebook, google, twitter, github, linkedin, microsoft, slack, amazon,
password, oauth2, oauth2second, oauth2third, ldap, and passwordless.
After paraClient.signIn() succeeds, the client caches the token and all subsequent requests to the API include it
until paraClient.signOut() is called.
To get or set access tokens use:
paraClient.getAccessToken();paraClient.setAccessToken(String token);To sign out and clear the token use:
paraClient.signOut();To invalidate all tokens for the signed-in user use:
paraClient.revokeAllTokens();Provider configuration example
For the browser sign-in flow, add the provider credentials to your para-application.conf configuration file. The
REST POST /jwt_auth call uses a provider token, so it does not use these OAuth client credentials.
# facebookpara.fb_app_id = "..."para.fb_secret = "..."# googlepara.gp_app_id = "..."para.gp_secret = "..."# linkedinpara.in_app_id = "..."para.in_secret = "..."# twitterpara.tw_app_id = "..."para.tw_secret = "..."# githubpara.gh_app_id = "..."para.gh_secret = "..."# microsoftpara.ms_app_id = "..."para.ms_secret = "..."# slackpara.sl_app_id = "..."para.sl_secret = "..."# amazonpara.az_app_id = "..."para.az_secret = "..."# generic oauth2para.oa2_app_id = "..."para.oa2_secret = "..."# second generic oauth2para.oa2second_app_id = "..."para.oa2second_secret = "..."# third generic oauth2para.oa2third_app_id = "..."para.oa2third_secret = "..."See the identity provider pages for provider-specific setup.