Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@
"expanded": true,
"pages": [
"ecosystem/api/toncenter/get-api-key",
"ecosystem/api/toncenter/v2-authentication",
{
"group": "API v2",
"openapi": {
Expand Down
74 changes: 74 additions & 0 deletions ecosystem/api/toncenter/v2-authentication.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
title: "Authentication for API v2"
---

## Overview

The API v2 requires an API key for all methods, including the JSON-RPC endpoint.
The key can be sent either in an HTTP header or as a query parameter.

To obtain an API key, see the [TON Center API key guide](/ecosystem/api/toncenter/get-api-key).

| Type | Location | Name | Required |
| ------- | -------- | ----------- | -------- |
| API key | Header | `X-API-Key` | Yes |
| API key | Query | `api_key` | Yes |

Only one of these is needed per request.

## REST endpoints authentication

### Header authentication

Send the API key in the `X-API-Key` header:

```bash
curl "https://<HOST>/api/v2/getMasterchainInfo" \
-H "X-API-Key: <API_KEY>"
```

**Definitions:**

- `<HOST>` - The base URL of the TON Center API instance (`toncenter.com` for example).
- `<API_KEY>` - The API key obtained from the [TON Center bot](https://t.me/toncenter).

### Query parameter authentication

Pass the key as a query parameter named `api_key`:

```bash
curl "https://<HOST>/api/v2/getMasterchainInfo?api_key=<API_KEY>"
```

Both forms are equivalent.

## JSON-RPC endpoints authentication

Endpoint: `POST /api/v2/jsonRPC`

The same API key rules apply. Example using header authentication:

```bash
curl "https://<HOST>/api/v2/jsonRPC" \
-H "Content-Type: application/json" \
-H "X-API-Key: <API_KEY>" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "getMasterchainInfo",
"params": {}
}'
```

Or using the query parameter:

```bash
curl "https://<HOST>/api/v2/jsonRPC?api_key=<API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "getMasterchainInfo",
"params": {}
}'
```