User API Keys

These API keys are granted on a user-per-user basis and allow access to the accounts which are owned by the user.

Each API key is associated with a user and can be used to access all or a subset of the accounts which are owned by the user (as specified by the accountIds field).

Keys can be whitelisted to certain IP addresses (as specified by the ips field).

Create a User API Key

import { UserApiKey } from '@tradrapi/trading-sdk';
 
const key: UserApiKey = await tradrApi.users.createApiKey({
  // The TradrAPI User ID this key belongs to
  userId: 121,
  // The roles which this API key can access
  roles: ['read', 'write'],
  // The name of this key, generally specified based on it's intended use
  friendlyName: 'My Personal Key',
  // Only allow requests from the provided array of IPs, leave empty to allow all IPs
  ips: [],
  // The IDs of the accounts which this API key can access, leave empty to allow all accounts
  accountIds: [],
});

The format of the UserApiKey model which is returned as a response from the functionality described below is as follows:

export enum UserRole {
  Read = 'read',
  Write = 'write',
  Delete = 'delete',
}
 
interface UserApiKey {
  /** The TradrAPI ID of the entity */
  id: number;
  /**
   * The date the entity was created
   * @format date-time
   */
  createdAt: string;
  /**
   * The date the entity was last updated
   * @format date-time
   */
  updatedAt: string;
  /** The roles assigned to the key. Roles determine what actions the key can perform */
  roles: UserRole[];
  /** The id of the user the API key belongs to */
  userId: number;
  /** A friendly name for the API key */
  friendlyName?: string;
  /** The API key (hashed) */
  apiKey: string;
  /** The IPs the API key can be used from. Empty array means any IP is allowed */
  ips?: string[];
  /** The ids of the accounts which can be managed by this key. Empty array means no accounts */
  accountIds?: number[];
  /**
   * The last time the key was used
   * @format date-time
   */
  lastUsedAt?: string;
}

⚠️

Please note that you will only ever be able to retrieve the API key once, when it is created. If you lose the API key you will need to create a new one.

Using a User API Key

Once you have created a user API key, you can use it to authenticate your requests to the API.

import { Tradr } from '@tradrapi/trading-sdk';
 
export const tradrApi = Tradr.make({
  // Bootstrap the SDK with your User API key
  auth: { apiKey: 'YOUR_USER_API_KEY' },
});

Fetch a User API Key

Returns a single user API key by its ID.

import { UserApiKey } from '@tradrapi/trading-sdk';
 
const key: UserApiKey = await tradrApi.users.getApiKey(32452);

List User API Keys

Returns a list of all API keys associated with the user.

The method accepts an userId as a parameter and returns a list of all user level API keys belonging to the user.

Please note that the userId is available under the AccountResult object when fetching an account. For further information, please see the AccountResult section.

import { UserApiKey } from '@tradrapi/trading-sdk';
 
const keys: UserApiKey[] = await tradrApi.users.listApiKeys(101004444);

Update a User API Key

Allows for the modification of an existing user API key. The key must be owned by the authenticated user.

const result: boolean = await tradrApi.users.updateApiKey({
  userApiKeyId: 23122,
  friendlyName: 'My renamed key',
});

Deleting a User API Key

An existing user level API key can be deleted by calling the deleteApiKey method.

const result: boolean = await tradrApi.users.deleteApiKey(23122);

This method accepts an userApiKeyId as a parameter and returns a boolean indicating whether the API key was deleted.

Account API Keys Overview