Cotter's OAuth 2.0 Tokens Specification

Allowing Cotter handling your full authentication is the fastest way to get your whole authentication suite setup. Cotter can generate an access token, id token, and refresh tokens for you.

Handling Authentication
After successful authentication, Cotter returns ID, access, and refresh tokens as defined by the OpenID Connect (OIDC) open standard:
The ID Token contains information about the authenticated user such as email , phone number , client_user_id (the user's id in your server), and auth_time (last authenticated time).
The Access Token contains scopes and the authentication method used to authenticate the user: OTP, TRUSTED DEVICE , PIN or BIOMETRIC .
The Refresh Token contains the information necessary to obtain a new ID and access token.
🔒It is important to secure all tokens in transit and storage.
Client Libraries
Currently, we have the following libraries available to handle Cotter's OAuth Tokens:
Cotter Token JS for Decoding JWT Tokens: cotter-token-js 
Cotter Node for validating JWT Tokens in your server: cotter-node 
Cotter's Access Token
Cotter's Access token is a JSON Web Tokens (JWTs) that is used to tell your backend API that the user has been authorized to call the API and perform some action (defined in the scopes attribute of the token). 
Access tokens expires every 1 hour. Check the guide on renewing access and id tokens.
Token example:
Access Token
1
eyJhbGciOiJFUzI1NiIsImtpZCI6IlNQQUNFX0pXVF9QVU...
Copied!
Example decoded token
1
{      
2
  "sub": "09efb1b-e50f-41fd-8530-88ffbcd80f59",                  // [Deprecated] Cotter's User id
3
  "client_user_id": "09efb1b-e50f-41fd-8530-88ffbcd80f59",       // deprecated
4
  "authentication_method": "TRUSTED_DEVICE",                     // How the user is authenticated
5
  "type": "access_token", 
6
  "identifier": "[email protected]",                   // User's email or phone number
7
  "scope": "access",                                  // Scope of this access token (coming soon)
8
  "aud": "<your API KEY ID>",                         // Your API_KEY_ID
9
  "exp": 1586231136,                                  // Expires at
10
  "iat": 1586227536,                                  // Issued at
11
  "jti": "47fba8ba-abcd-efgh-a22c-a2b8b72e8b98",
12
  "iss": "https://www.cotter.app"            
13
}
Copied!
How to use the Access Token to allow API calls
1. On every API call to your server, attach the access token as a header
1
Authorization: Bearer <access token>
Copied!
2. In your server, using a middleware, check if the access token is valid
Verifying JWT Tokens
3. If the access token is valid, allow the API call to proceed.
Cotter's ID Token
Cotter's ID token is a JSON Web Tokens (JWTs) that is used to provide information about the user. ID tokens expires every 1 hour. Check the guide on renewing access and id tokens.
Example Decoded Token
1
{
2
  "sub": "43e53999-c31e-4ed9-a196-71031a05f297",              // [Deprecated] Cotter User ID
3
  "client_user_id": "43e53999-c31e-4ed9-a196-71031a05f297",   // Deprecated
4
  "auth_time": "1591756112",                                  // Last authenticated time (Unix timestamp)
5
  "identifier": "[email protected]",
6
  "type": "id_token",
7
  "aud": "<your API KEY ID>",       // your API KEY ID
8
  "exp": 1586232181,                // Expires at
9
  "iat": 1586228581,                // Issued at
10
  "jti": "886773db-abcd-efgh-aefc-6ab481b24099",
11
  "iss": "https://www.cotter.app"
12
}
Copied!
You should not trust this information after it's expired
Cotter's Refresh Token
Cotter's Refresh Token is an opaque token (i.e. a random string) that is used to generate a new access token and id token when they're expired. Refresh tokens expires every 30 days. You need to re-authenticate the user to get a new refresh token. Check the guide on renewing access and id tokens.
1
14:Pmw3r3rgaw0rLupUDU4hjwJFisv8EaHRaoy5gw54ZmSebaWHDh
Copied!
🥳 Getting Started
1. Getting The Tokens using the SDK
Easily get tokens using the SDK by adding a simple paramater, ex. getOAuthToken = true
Getting the Tokens
2. Storing & Removing the Token
The SDK generally automatically store tokens securely for you, and provides a function to easily remove the tokens to logout your users.
Storing and Removing Tokens
3. Renewing Expired Tokens
The SDK generally automatically renews expired access_token and id_token whenever a valid refresh_token exists.
Renewing Expired Tokens
4. Verifying the Tokens
You need to verify the JWT tokens in your backend server. Fortunately, there are a lot of good libraries that do this.
Verifying JWT Tokens
5. Adding Custom Claims to your JWT Token
If you have additional metadata from your backend server that you'd like to add to the JWT token (for example, the user's role or name, you can call Cotter's API to add the claims to Cotter's JWT token 
Requesting Custom Claims on your Access Token
🎉 You're done!