Skip to content

API Authentication

The Para API offers a few options for authentication. Para API clients can call the API authenticated either as users or apps:

PrincipalMethodCredentialsAccess
AppSigned request (AWS v4)Access key and secret keyFull API access
AppApp JWTSigned with app’s secret keyFull API access
UserUser JWT, also called a personal access token (PAT)Signed with user’s secret + app secretRestricted 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.

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 HS256 algorithm
  • contain the appid claim
  • 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._MKAH6SGiKSoqgwmqUaxuMyE

When 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.

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”:

Postman Authorization tab with the AWS Signature type selected
FieldDescription
Access KeyYour Para access key, e.g. app:myapp.
Secret KeyYour Para secret key.
RegionAlways us-east-1.
Service NameAlways para.

Make sure you don’t have extra headers in your requests because Postman is known to calculate invalid signatures for such requests.

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.

Call POST /jwt_auth with the app ID, the provider, and the provider token:

POST /jwt_auth
Content-Type: application/json
{
"appid": "app:myapp",
"provider": "password",
"token": "[email protected]::password123"
}

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.

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.

para-application.conf
# facebook
para.fb_app_id = "..."
para.fb_secret = "..."
# google
para.gp_app_id = "..."
para.gp_secret = "..."
# linkedin
para.in_app_id = "..."
para.in_secret = "..."
# twitter
para.tw_app_id = "..."
para.tw_secret = "..."
# github
para.gh_app_id = "..."
para.gh_secret = "..."
# microsoft
para.ms_app_id = "..."
para.ms_secret = "..."
# slack
para.sl_app_id = "..."
para.sl_secret = "..."
# amazon
para.az_app_id = "..."
para.az_secret = "..."
# generic oauth2
para.oa2_app_id = "..."
para.oa2_secret = "..."
# second generic oauth2
para.oa2second_app_id = "..."
para.oa2second_secret = "..."
# third generic oauth2
para.oa2third_app_id = "..."
para.oa2third_secret = "..."

See the identity provider pages for provider-specific setup.