Partner API Authentication

This guide will walk you through generating an access token and making your first request to the Tradevest API.

1. Prerequisites

Before you begin, ensure you have gathered your credentials and identified the correct environment URLs.

Client Credentials

You will need a client_id and client_secret. These are provided by the Tradevest support team.

Environment URLs

Service	Sandbox (Testing)	Production (Live)
Authentication URL	`https://b2b.auth.platform-test.tradevest.ai`	`https://b2b.auth.platform-prod.tradevest.ai`
API Base URL	`https://tvda-api.platform-test.tradevest.ai`	`https://tvda-api.platform-prod.tradevest.ai`

2. Authenticate (Get a Token)

Tradevest uses the OAuth 2.0 Client Credentials flow. You must exchange your credentials for a temporary access token at the Auth URL.

The Request

Send a POST request to the token endpoint using application/x-www-form-urlencoded.

# Example for Sandbox Environment
curl -X POST https://b2b.auth.platform-test.tradevest.ai/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>"

See Get Token in the API reference for the full contract.

The Response

If successful, you will receive a Bearer token valid for 1 hour (3600 seconds).

{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Important

Security Note: Treat your client_secret like a password. Never include it in client-side code (mobile apps/browsers) or commit it to public repositories.

3. Make Your First Request

Now that you have a token, you can access protected resources at the API Base URL. Include the token in the Authorization header.

Endpoint: GET /traditional/assets

# Note: Use the API URL here, not the Auth URL. Paths are not version-prefixed.
curl -X GET "https://tvda-api.platform-test.tradevest.ai/traditional/assets?limit=10" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

4. The Requestor-ID Header

To ensure auditability and regulatory compliance, most operations require you to identify the specific individual performing the action.

The Header

Requestor-ID: <UUID-OF-ENTITY>

Note

When is this NOT required? You do not need to include the Requestor-ID for:

Authentication: The token exchange step.
Onboarding: Creating a new Natural Person or Legal Entity.

Warning

Mandatory Requirement For all other commands (e.g., "Create Market Order"), the Requestor-ID is mandatory. Requests missing this header will return a 400 Bad Request or 403 Forbidden.

Important

Requestor-ID Validation: The Requestor-ID must reference a natural person that is in ACTIVE status. If the referenced natural person is not active (e.g., SUSPENDED, BLOCKED, or CREATED), the operation will be rejected with a VALIDATION_ERROR. This applies to all operations that require the header, including order placement.

Requestor-ID and Proxy Authorization

The Requestor-ID identifies the natural person performing the action. Authorization is resolved as follows:

Direct action (self): If the Requestor-ID matches the target entity ID, the action is authorized directly - the natural person is acting on their own behalf.
Proxy action (on behalf of another entity): If the Requestor-ID does not match the target entity, the system checks whether the natural person has an ACTIVE proxy relationship with the target entity. If an active proxy exists where the natural person is authorized to represent the target entity (natural person, legal entity, or joint person), the action is authorized.

In both cases, the natural person referenced by Requestor-ID must be in ACTIVE status. If no direct match or active proxy relationship is found, the request is rejected with Requestor-ID invalid.