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 Token via JWKS (opens in a new tab)
- API Keys
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:
Role | User Level Access | Admin Level Access |
---|---|---|
Read | Read | Viewer |
Write | Write | Manager |
Delete | Delete | Manager |
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.