# Authentication

Every API endpoint that starts with `/volven-broker/api/` requires API key authentication.\
Every API endpoint that starts with `/volven-broker/public/` doesn't require any authentication.

#### API Key Authentication

Every request requires following authentication related HTTP headers:

* `X-API-Key`
* `X-API-Timestamp`
* `X-API-Signature`

Some requests require following business related HTTP headers:

* `X-API-User-ID`

{% hint style="danger" %}
Never share your API secret with anyone, even with TÝR Markets employees. Use it internally to sign your request. Make sure to store it securely. Stolen API secret may lead to lost funds.
{% endhint %}

#### X-API-User-ID

Some endpoints require `X-API-User-ID` header to identify the user for whom the action is executed. It can be any user that has been registered via your partner account (if you want to perform the action in the name of one of your users) or can be your partner account (if you want to perform the action as yourself). Check OpenAPI documentation for details.

{% hint style="warning" %}
If user ID is incorrect then `400 Bad Request` will be returned.

If user was not registered via you then `403 Forbidden` will be returned.
{% endhint %}

#### X-API-Key

`X-API-Key` is simply your API Key (example: `0408ad13-cd74-4e99-8fe5-9fd2badd42ec`).

{% hint style="warning" %}
If `X-API-Key` is missing or invalid then `401 Unauthorized` will be returned
{% endhint %}

#### X-API-Timestamp

`X-API-Timestamp` must be actual timestamp in Unix epoch format with millisecond precision (example: `1760721374734`). When the server receives the message it verifies if current time is same as `X-API-Timestamp` value with 5000 ms tolerance.

{% hint style="warning" %}
If `X-API-Timestamp` is missing or time drift is bigger than 5000 ms then `401 Unauthorized` will be returned
{% endhint %}

#### X-API-Signature

`X-API-Signature` is calculated in following way:

1. Prepare canonical request:  timestamp + method + path (with query string, if any) + user ID (if any) + body
2. Sign canonical request with you API Secret using HMAC SHA256 algorithm
3. Encode the signature in Base64 format.

Example:

Assume you request looks like this:

```http
POST /volven-broker/api/orders
X-API-User-ID: 789
{"orderType": "MARKET", "quoteId": "d285d287-5ab6-453b-99ed-ca1765b4231a", "side": "BUY"}
```

Canonical request would look like this:

```
1760721374734POST/volven-broker/api/orders789{"orderType": "MARKET", "quoteId": "d285d287-5ab6-453b-99ed-ca1765b4231a", "side": "BUY"}
```

Final signature would look like this:

```
wUCAlLkxQrOhOi95eheYmcL9mdHjinWvO4vTyDN+Uko=
```

{% hint style="warning" %}
If signature doesn't match then `401 Unauthorized` will be returned
{% endhint %}

#### Final request

Finally, correctly authenticated request will look like this:

```http
POST /volven-broker/api/orders
X-API-User-ID: 789
X-API-Key: 0408ad13-cd74-4e99-8fe5-9fd2badd42ec
X-API-Timestamp: 1760721374734
X-API-Signature: wUCAlLkxQrOhOi95eheYmcL9mdHjinWvO4vTyDN+Uko=
{"orderType": "MARKET", "quoteId": "d285d287-5ab6-453b-99ed-ca1765b4231a", "side": "BUY"}
```

This ensures that the server can verify the authenticity of the request by comparing the received signature with its own calculation. By using these elements — `X-API-Key`, `X-API-Timestamp`, and `X-API-Signature` — your API requests will be secure from replay attacks while maintaining data integrity.


---

# 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.volven.io/api/tyr-markets-partner-api/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.