# 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`.

```bash
# Example for Sandbox Environment
curl -X POST https://b2b.auth.platform-test.tradevest.ai/connect/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>" \
  -d "scope=tradevest.api"
```

#### The Response

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

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

{% hint style="danger" %}
**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.
{% endhint %}

***

### 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 /prices`

```bash
# Note: Use the API URL here, not the Auth URL
curl -X GET https://tvda-api.platform-test.tradevest.ai/v1/prices?symbol=BTC \
  -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>`

{% hint style="info" %}
**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.
  {% endhint %}

{% hint style="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`.
{% endhint %}

{% hint style="danger" %}
**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.
{% endhint %}

#### Requestor-ID and Proxy Authorization

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

1. **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.
2. **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`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tradevest.ai/documentation/2_authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.