Skip to content

Authentication

The API uses a set of tokens and keys to authenticate requests. These items are provided as headers which must be included in each request.

Note

  • For standard production access, you will need to use the URL https://global-api.fintechstudios.com
  • A developer friendly front end is provided through our API Docs Page which can be used to review documentation and try out the API endpoints directly. You will need to be authorized by FinTech Studios for access to API Docs. You can request access at [email protected]

Keys

Keys are static strings used to identify the group or organization making the API request. Keys are generated by FTS and provided to authorized users as a 36-character UUID of the form: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Please contact your account manager or sales representative to receive an access key.

Safety First

Do not share your access key. It is unique to your organization, and used to identify requests made on your behalf.

Keys are provided by adding an x-api-key header to your request, with your key as the value. For example, if your key was f83527a1-53c9-4947-b2b3-0d4f208858f2, then you would add the following header to each request:

x-api-key: f83527a1-53c9-4947-b2b3-0d4f208858f2

Tokens

While access keys may be static, tokens are a bit different. Tokens are short-lived access codes used to authenticate requests as a unique user. The access tokens used to authenticate with the API are called JSON Web Tokens, or JWT for short. These tokens are then used to sign each API request using the Authorization header.

To receive an access token, simply make a POST request to the /auth/token endpoint:

    {
      "email": "string",
      "password": "string"
    }

    {
      "token": "string",
      "expires": "integer",
      "userId": "string"
    }

The token field is the JWT that you will use to authorize API requests. This token is temporary, and will expire after the timestamp identified in the expires field as a Unix timestamp. To authorize API requests using the token, simply add the JWT as a bearer token to the Authorizationheader in each request:

authorization: Bearer eyJhbGciOiJSUzI1NiIsIn...

While testing, it's perfectly acceptable to manually fetch a token periodically to authenticate your requests. However, you'll need to automate this in a live deployment. FTS recommends using a token refreshing process to refresh tokens prior to expiration. This process should be periodic and located in a backend system to avoid exposing credentials to end-users.

Danger

Do not request a new token for each API request. You should re-use tokens until they expire. Excessive requests may result in throttling or disabling of accounts.

Putting It Together With an Example

Putting the previous two steps together, we see that each API request requires two forms of authorization: an access key and a token. While access keys are static, tokens are dynamic and must be refreshed occasionally. Let's say we have an access key of 7a231ffe-3b9d-46d5-a1e7-654205d0b8f3, and a token of the following:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.ey
JzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikpva
G4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKx
wRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

You would then include the following headers with each API request to fully authorize it:

x-api-key: 7a231ffe-3b9d-46d5-a1e7-654205d0b8f3
authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Last update: March 14, 2022
Back to top