Migrating from ECDSA to OAuth2

📘

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

For now, no.

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.

You can implement OAuth2 for your existing app or create a new app and have us migrate data from your old app.

👍

Client ID and Secret

If you are implementing the OAuth2 method for an established ECDSA app, you will need to reach out to us to create a client ID and secret for you.

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 before moving on the the Implementation section of this guide.

Postman Collection

Find it here.

Implementation

If you are not currently utilizing our SDKs, move forward with implementing a conventional JWT/OAuth2 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]