Authentication

How authentication works in Cord and best practices with JWTs

ℹ️ Before December 2023, authentication worked a little differently. Previously, we required client tokens to be signed with group (org) IDs. We now recommend omitting this for a more flexible user experience. The old approach continues to be supported. See here to learn more.

Project 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 project ID and the ID for the user.

The client auth token's payload can include these fields:

project_id #

required

uuid

Your project ID

user_id #

required

string

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

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.

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 Projects API. Refer to the section below on Project management auth tokens for guidance on the token needed to use the project api.

The server auth token's payload only contains one field:

project_id #

required

uuid

Your project ID

Project management auth token #

Since server auth tokens are specific to a project, we require a higher level authentication token to make calls to our Projects REST API.

This is where the project management auth token comes in. It is a customer-level JWT used to authorize your server to make calls to the Projects 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 project management auth token's payload only contains one field:

customer_id #

required

uuid

Your customer ID

Not finding the answer you need? Ask our Developer Community

Ask Cordy