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

group_id #

required

string

This value can be any valid identifier. It must be unique per group 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.

group_details #

optional

object

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

If either the user_details or group_details fields are included, the user will be added to that group 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

Ask Cordy