Authentication

How authentication works in Cord and best practices with JWTs


Application authentication for the Cord components

💡 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

required
uuid
Your app ID

user_id

required
string
This value can be any valid identifier. It must be unique per user across your entire Cord application.

organization_id

required
string
This value can be any valid identifier. It must be unique per organization across your entire Cord application.

user_details

optional
object
If present, update's the user's details, or creates a user with those details if the user_id is new to Cord. This is an object that contains the same fields as the user management REST endpoint.

organization_details

optional
object
If present, update's the organization's details, or creates an organization with those details if the 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

required
uuid
Your 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:


customer_id

required
uuid
Your customer ID