Access Tokens

Access Tokens are short-lived credentials that can be distributed safely to client-side applications. They may be used to make authenticated requests to the Parra API on behalf of one of your users. To create an access token, you must sign a JSON Web Token (JWT) with your API Key Secret on your server and return it to your client to give it to the Parra SDK.

Getting Started

If your backend is supported by our quick start guides please follow our guide to get up and running. If your backend is not currently supported by our SDKs, we recommend you choose the JWT library for your respective platform instead of trying to create your own from scratch and continue on to sign an access token for your users.

Signing a JWT

An Access token is a JSON Web Token (JWT) in accordance to the open standard RFC 7519. To learn more about JWTs, please visit jwt.io.

Once you have installed a JWT library in your backend, you will need the following values:

API Key ID (PARRA_API_KEY_ID)
API Secret Key (PARRA_API_KEY_SECRET)
Tenant ID (PARRA_TENANT_ID)

To obtain these values, navigate to the settings section of the Parra Dashboard. The Tenant ID will be found in the General tab. Then navigate to the API Keys tab and create a new API Key. Record these values. Once you have all the values ready, you must construct the payload, headers, and claims for your JWT. Implementation will vary depending on the JWT library but all should support some form of the following instructuctions.

Include the following claims:

iss - your API Key ID
sub - your Tenant ID
*exp - calculate (now in seconds) + 3600

Include the following header parameters:

alg - use the value HS256
typ - use the value JWT
cty - use the value parra-fpa;v=1

Include the following JSON payload:

{
    "grants": {
        "identity": "<user-id>"
    }
}

where <user-id> is a string representation of a user ID in your system. For example, if your system uses integer identifiers the identity field must be populated with the stringified version of the ID value. Another common pattern is to prefix the identity with the type that it represents in your system like user|<id> or <your-company>|<id>.

Using your respective library, sign your JWT Payload using the HS256 algorithm and your API Secret Key. Once your JWT is signed, you can verify the payload by checking the JWT Debugger and inspecting the fields.

Returning the Access Token to your Client

You should securely transmit this access token using SSL over HTTP. For our guides, we use a POST /v1/parra/auth/token. And that's it. You may now start making authenticated requests to the Parra API with the access token you issued.

Public Access Tokens

Public access tokens are restricted access tokens for limited access to the Parra API by client applications. Parra offers an endpoint in our backend that may be used by apps that do not have their own backend to issue public access tokens, although securely signing the access token in your own backend is highly recommended for security reasons.

To issue a public access token, first generate a public API Key by visiting the API Keys section of the dashboard and creating an API Key with the "Public" option selected. Next, make a request to POST /v1/tenants/<tenant-id>/issuers/public/auth/token with a JSON body containing a single <user_id> field representing the stringified id of the user in your system (e.g. { "user_id": "123456" }). Include an Authorization header containing basic authentication with the username of api_key and the password of your API Key ID.

Basic authentication is the base 64 encoded string of the username and password joined by a colon following the formula Basic base64Encode(api_key:<api-key-id>). The secret field of a public access key is never exposed externally, but Parra uses it internally to sign your public access tokens.