SDKs
JavaScript/Typescript
Authentication

Authentication

In order to perform any action via the TradrAPI SDK (or via the REST interface directly), you must first authenticate with the API.

In TradrAPI there are different levels of authentication and each level supports multiple authentication methods.

For the scope of using the SDK at a user or project level, we are only interested in the user and admin levels (or scopes).

User Level Authentication

This level of authentication is used to perform actions on behalf of a user, for example if a user wants to open a new position or register a new account. User level authentication is also used to retrieve information about a user, such as their account balance or open positions.

It is important to note that if authenticated at a user level you can only perform actions on behalf of the user that you are authenticated as. For example, if you are authenticated as user1 you cannot open a position for user2.

Users are defined by the project (or brand) that they are associated with. For example, user1 may be a user of project A, whereas user2 may be a user project B. Each project may have multiple users and each user may have multiple accounts within TradrAPI.

The identifying ID of a user is owned by the project that the user belongs to, therefore the ID of a user is unique to that project.

User Authentication Methods

The following authentication methods exist for user level authentication:

JWT Tokens

This method of authentication requires the setup of a JSON Web Key Set (JWKS) by each project (brand) which wishes to authenticate their users with TradrAPI.

The JWKS is used to verify the authenticity of a JSON Web Token (JWT) which is generated by the project (brand) when a user logs in.

The project itself will generate a JWT token for their own user and TradrAPI will validate the authenticity of the token using the JWKS published by the project. If the token is valid, TradrAPI will then authenticate the user and allow them to perform actions on behalf of the user.

When using the JWT method of authentication, the SDK must be configured with a valid JWT token to use for authentication:

import { Tradr } from '@tradrapi/trading-sdk';
 
// Initialize the SDK with a JWT token
const tradrApi = Tradr.make({
  auth: {
    jwtToken: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MTIzNDU2Nzg5LCJuYW1lIjoiSm9zZXBoIn0.OpOSSw7e485LOP5PrzScxHb7SR6sAOMRckfFwi4rp7o',
  },
});

API Keys

There are multiple types of API keys. These are User API Keys, Account API Keys, and Project API Keys. Each type of API key has a different level of access.

An Account API Key can only be used to perform actions on behalf of a specific account. For example, if you have an account with ID 123456789 and you have an Account API Key belonging to the ID 987654321, you can only perform actions on behalf of the account with ID 987654321.

This is also true if both accounts belong to the same user.

A User API Key can be used to perform actions on behalf of any account belonging to the user that the API key belongs to.

TradrAPI allows individual users and accounts to have multiple API keys and allows each user or account to generate their own API keys.

When using the API key method of authentication, the SDK must be configured with a valid API key to use for authentication:

import { Tradr } from '@tradrapi/trading-sdk';
 
// Initialize the SDK with an API key
const tradrApi = Tradr.make({
  auth: {
    apiKey: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJeyJpZCI6MTIzNDU2Nzg5LCJuYW1lIjoiSm9zZXBoIn',
  },
});

Admin Authentication Methods

The SDK may also be used to perform actions on behalf of a project (brand). This is known as admin level authentication.

At this level of authentication the SDK will allow you to perform actions on behalf of any user or account belonging to the project (brand) that you are authenticated as, as well as perform actions on behalf of the project itself.

Admin Authentication Methods

The following authentication methods exist for admin level authentication:

  • API Key

A project API Key can be used to perform project level actions which are not specific to any user or account. This type of access is only available to admin level authentication.

API Keys

Irrelevant of the level of authentication, each API key can be created with a specific role which restricts the overall level of access.

For User level authentication, the following roles are available:

  • Read
  • Write
  • Delete

For Admin level authentication, the following roles are available:

  • Logs
  • Viewer
  • Manager

The following table shows the level of access that each role has:

RoleUser Level AccessAdmin Level Access
ReadReadViewer
WriteWriteManager
DeleteDeleteManager

TradrAPI also offer access to server level logs. This is only available to admin level authentication and requires the Logs role.

API keys may also be IP restricted. This means that the API key can only be used from a specific IP address or range of IP addresses.

We highly recommend that whenever creating an API key, you restrict the IP address that the API key can be used from.