Next Perpendicular Moonlanding

    This package has been deprecated

    Author message:

    WARNING: This package has been renamed to cotter-token-js. Install using cotter-token-js instead

    cotter-jwt-js

    0.1.0 • Public • Published

    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_idstring;
    authentication_methodstring;
    typestring;
    scopestring;
     
    // standard claims
    audstring;
    expnumber;
    jtistring;
    iatnumber;
    issstring;
    nbfnumber;
    substring;

    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_idstring; // user id from your server
    auth_timestring; // last authentication time
    identifiersstring[]; // email/phone number
    typestring;
     
    // standard claims
    audstring;
    expnumber;
    jtistring;
    iatnumber;
    issstring;
    nbfnumber;
    substring;

    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);
    });

    Install

    npm i cotter-jwt-js

    DownloadsWeekly Downloads

    5

    Version

    0.1.0

    License

    ISC

    Unpacked Size

    10.4 kB

    Total Files

    7

    Last publish

    Collaborators

    • putrikarunia
    • albertputrapurnama
    • julianna-stytch