Cotter JWT Classes for JS

Read and decode jwt tokens generated by Cotter using the classes defined here. To read more about Cotter, get started with our 📚 integration guides and example projects.

Install

npm install cotter-jwt-js --save

or

yarn add cotter-jwt-js

Usage

To decode a jwt token:

import { CotterJwtToken } from "cotter-jwt-js";

const decodedToken = new CotterJwtToken(token);

console.log(decodedToken.payload); // decoded jwt token object

console.log(decodedToken.token); // original token string

Expiry, IssuedAt, and Audience

// getting payload.exp
const expiredAt = decodedToken.getExpiration();

// getting payload.iat
const issuedAt = decodedToken.getIssuedAt();

// getting payload.aud
const audience = decodedToken.getAudience();

Usage with Cotter

Cotter returns 2 types of jwt token, CotterAccessToken and CotterIDToken.

CotterAccessToken

This access token should be passed to your backend server, and used to authorize users to access your API. Validate the access token passed to your backend server using this example.

To decode a the access token:

import { CotterAccessToken } from "cotter-jwt-js";

const decodedToken = new CotterAccessToken(accessToken);

console.log(decodedToken.payload); // decoded jwt token object

console.log(decodedToken.token); // original token string

CotterAccessToken have the following attributes

client_user_id: string;
authentication_method: string;
type: string;
scope: string;

// standard claims
aud: string;
exp: number;
jti: string;
iat: number;
iss: string;
nbf: number;
sub: string;

CotterAccessToken also extends all the methods available for CotterJWTToken.

CotterIDToken

The ID token is following OpenID specifications, and is provided to get more information about the user.

To decode a the id token:

import { CotterIDToken } from "cotter-jwt-js";

const decodedToken = new CotterIDToken(accessToken);

console.log(decodedToken.payload); // decoded jwt token object

console.log(decodedToken.token); // original token string

CotterIDToken have the following attributes

client_user_id: string; // user id from your server
auth_time: string; // last authentication time
identifiers: string[]; // email/phone number
type: string;

// standard claims
aud: string;
exp: number;
jti: string;
iat: number;
iss: string;
nbf: number;
sub: string;

CotterIDToken also extends all the methods available for CotterJWTToken.

Getting Access Token from Cotter

When you want to request access tokens from cotter, add a query paramater ?oauth_token=true at the end of your request.

For reference, current base url for Cotter:

https://www.cotter.app/api/v0

There are several endpoints where you can request access tokens from:

1. Create User Endpoint

POST /user/create?oauth_token=true

2. Update Methods Endpoint

PUT /user/:client_user_id?oauth_token=true

3. Create Approved Event Request Endpoint

POST /event/create?oauth_token=true

4. Get Event Request Endpoint

GET /event/get/:event_id?oauth_token=true

5. Get Identity Endpoint (using PKCE flow)

GET /verify/get_identity?oauth_token=true

When using these endpoints, you'll get an additional field called oauth_token:

Response

{
  ...
  "oauth_token": {
    "access_token": "eyJhbGciOiJFUzI1sInR5cC...",
    "auth_method": "TRUSTED_DEVICE",
    "expires_in": 3600,
    "id_token": "eyJhbGciOiJFUz...",
    "refresh_token": "60:79hbLxl3aTjWWgCcIRnn...",
    "token_type": "Bearer"
  }
}

Request Token Explicitly

You can also request access tokens separately by passing in an identity_token or an event_token using these endpoints

Get Token using Identity Token

When you receive an Identity Token from Cotter's Email/Phone Number Verification SDK, you can pass it to this endpoint to receive an access token.

POST /token
Content-Type: application/json
API_KEY_ID: <API-KEY-ID>

{
  "grant_type": "identity_token",
  "identity_token": {
    "identifier_id": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
    "timestamp": "1585988231",
    "identifier": "hello@cotter.app",
    "identifier_type": "EMAIL",
    "receiver": "12341234-1234-1234-1234-123412341234",
    "expire_at": "1588580231",
    "signature": "BiyuaWwk2PVsNt0J3...
  }
}

Response

{
  "access_token": "eyJhbGciOiJFUzI1sInR5cC...",
  "auth_method": "OTP",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUz...",
  "refresh_token": "60:79hbLxl3aTjWWgCcIRnn...",
  "token_type": "Bearer"
}

Get Token using Event Token

When you receive an Event Token from Cotter's Trusted Device or PIN/Biometric SDK, you can pass it to this endpoint to receive an access token.

POST /token
Content-Type: application/json
API_KEY_ID: <API-KEY-ID>


{
  "grant_type": "event_token",
  "event_token": {
    "CreatedAt": "2020-04-05T02:24:05.939179-07:00",
    "DeletedAt": null,
    "ID": 462,
    "UpdatedAt": "2020-04-05T02:24:05.939179-07:00",
    "approved": true,
    "client_user_id": "xyzABC1234",
    "event": "LOGIN",
    "ip": "73.15.208.6",
    "issuer": "12341234-1234-1234-1234-123412341234",
    "location": "Orinda",
    "method": "TRUSTED_DEVICE",
    "new": false,
    "signature": "XeKPx6HoZeKCTzdbLorE...",
    "timestamp": "1586078645"
  }
}

Response

{
  "access_token": "eyJhbGciOiJFUzI1sInR5cC...",
  "auth_method": "TRUSTED_DEVICE",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUz...",
  "refresh_token": "60:79hbLxl3aTjWWgCcIRnn...",
  "token_type": "Bearer"
}

Get Token using Refresh Token

When your access token expires, you can get a new one using the refresh token that was given.

POST /token
Content-Type: application/json
API_KEY_ID: <API-KEY-ID>


{
  "grant_type": "refresh_token",
  "refresh_token": "3:8xhGfVzGa91WOZ1eDk..."
}

Response

Note that you don't get a refresh token back.

{
  "access_token": "eyJhbGciOsInR5cCI6...",
  "auth_method": "OTP",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUzI1NiI...",
  "token_type": "Bearer"
}

Validating JWT Token

To validate the jwt token, you need Cotter's JWT Public Key. The Public Key is specified in this endpoint:

GET /token/jwks

There's only one key for now, so use that key.

To Validate jwt token using this key, check the example

A simple example to validate the jwt token:

var jwt = require("jsonwebtoken");
var jwkToPem = require("jwk-to-pem");

const publicKeys = await axios.default.get(
  "https://www.cotter.app/api/v0/token/jwks"
);
const jwk = publicKeys.data.keys[0];
const pem = jwkToPem(jwk);
jwt.verify(token, pem, { algorithms: ["ES256"] }, function (err, decodedToken) {
  console.log(err);
  console.log(decodedToken);
});