Authentication
How authentication works in Cord and best practices with JWTs
💡 This page gives the details behind authentication. Our server libraries have functions for generating auth tokens, which abstract away these details. We recommend using those libraries, unless your backend uses a language for which we don't offer a server library.
Background
All authentication in Cord uses JSON Web Tokens (JWTs). A JWT consists of a JSON payload, plus a cryptographic signature generated using a secret.
The payload contains information from the JWT signer that the verifier needs. We use two different payloads: one for client auth tokens and another for server auth tokens, so as to include only the information we need in each context.
You can find your secret in the Cord console; use it to sign all JWTs you send to Cord.
You must generate all tokens on your backend. From there, you'll send client auth tokens to your frontend, and server auth tokens directly to Cord's servers.
⚠️ Store your secret securely on your servers. Don't share it with anyone, and don't include it in client code.
Signing
Sign all JWTs using the HS512 (HMAC with SHA-512) algorithm.
JWTs include an expiration time. For security, you should set the expiration of your JWTs to a short interval. Our recommendation is 1 minute, which very safely accounts for any network delays and clock skew.
Verifying
If you set a custom redirect link, you'll need to verify JWTs that Cord's servers send to your servers. They will be signed with your secret, using HS256.
Use a JWT library for your language to verify the JWTs you receive before doing anything with their contents.
Client auth token
A client auth token is a JWT used to authorize a user to Cord in the browser. It must include your app ID, the ID for the user, and the ID for the organization the user is acting within.
The client auth token's payload can include these fields:
app_id
user_id
organization_id
user_details
user_id is new to Cord. This is
an object that contains the same fields as the user management REST
endpoint.organization_details
organization_id is new to Cord. This is an object that contains the same
fields as the organization management REST
endpoint.If either the user_details or organization_details fields are included, the user will be added to that organization if they aren't already a member. If neither is specified and the user isn't a member, the token will produce an error if used.
Server auth token
A server auth token is a JWT used to authorize your server to make calls to all of our REST API endpoints except for the Applications API. Refer to the section below on Application management auth tokens for guidance on the token needed to use the applications api.
The server auth token's payload only contains one field:
app_id
Application management auth token
Since server auth tokens are specific to an application, we require a higher level authentication token to make calls to our Applications REST API.
This is where the application management auth token comes in. It is a customer-level JWT used to authorize your server to make calls to the Applications API. For all other APIs, you should use a server auth token.
When signing this token, the secret key used should be your customer secret which can be found in the Cord Console.
The application management auth token's payload only contains one field:
