Migrating from ECDSA to JWT Auth Token

A guide for existing customers that want to migrate from ECDSA to JWT Auth Token authentication.

📘

Am I required to switch if I'm using ECDSA?

No, however we do highly recommend it. While there is currently no ETA, we do plan to eventually sunset ECDSA authentication and only support JWT Auth Token authentication.

Use a JWT auth token instead of private keys for signing requests.

Useful documentation

JWT Auth Token Overview

/auth_token endpoint

SDKs

We created our SDKs for the main purpose of assisting with signing requests using ECDSA authentication.

JWT Auth Token authentication is NOT supported by our SDKs.

If you are currently utilizing our SDKs, you will need to implement making requests using HTTP request protocol.

Postman Collection

Find it here.

To Implement

If you are not currently utilizing our SDKs, implement a conventional JWT/OAuth authentication flow:

  • Retrieve a JWT token by calling the /auth_token endpoint using HTTP Basic authentication.
  • Use that JWT token for all other API endpoints, using HTTP Bearer authentication.

/auth_token endpoint

Use this endpoint to generate an auth token to authenticate subsequent API requests, or to invalidate a token.

  • This token has an 8-hour expiry window.
  • The /auth_token doc includes details on:
    • Building and encoding an HTTP Basic Authentication credentials string, required for this request
    • Request and response specs
  • The token object returned will include three attributes:
    • token - string: an alpha-numeric 205 character string that will be passed back for the base64-encoded token value in the Bearer token authorization header for subsequent API calls.
    • expiration - int: an epoch timestamp designating the expiration timestamp in UTC.
    • expiration_dt - string: a human-friendly date/time representation of the expiration timestamp; conforms to ISO 8601 date and time format in UTC.

Auth token caching

You should cache or store the auth token object in your database and continue using the same token until its expiration time is less than 30 minutes.

  • If you re-request a token for your app while your current token has more than 30 minutes left before it expires, the API will return the same token from the previous request.
  • Only when your token has less than 30 minutes left of the expiry window will a new token be issued with a new, full 8-hour window.

How to authorize requests with a JWT Auth Token

After retrieving your token from calling /auth_token, you will include the token as part of the authorization header of all your API requests.

Authorization: Bearer [GENERATED 205 char JWT TOKEN HERE]