Skip to content

Add TON Center API v2 auth details page #1494

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
laviniat1996 wants to merge 5 commits into
base: main
Choose a base branch
from
+75 −0
Draft

Add TON Center API v2 auth details page #1494

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ded2e02
add api v2 auth details page
laviniat1996 Dec 1, 2025
80aadba
fix linting
laviniat1996 Dec 1, 2025
3a88548
address ai comments
laviniat1996 Dec 1, 2025
7898b80
Merge branch 'main' into v2-auth
laviniat1996 Dec 2, 2025
293346e
Merge branch 'main' into v2-auth
reveloper Dec 8, 2025
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,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
View file
Open in desktop
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.
Copy link
Collaborator

@reveloper reveloper Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Screenshot 0007-12-08 at 14 57 14

The requirement of the API key should be specified accurately. An API key is required if the developer desires to make more than one request per second. There is no method that is fully limited by the API Key, just for RPS>1 user will get the HTTP Error 429:

Screenshot 0007-12-08 at 15 04 37

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).
Copy link
Collaborator

@reveloper reveloper Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have any expiration limit on the API key? Are there any recommendations to rotate the API key?


Copy link
Collaborator

@reveloper reveloper Dec 8, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a danger reminder of the importance of securely storing the API key.

Example:

Security
Prefer read‑only tokens for public access, scope server 
tokens to only what you need, rotate long‑lived 
tokens, and store them in a secrets manager. 
Never expose admin tokens in client‑side code.

Extra reference: https://docs.stripe.com/keys-best-practices

| 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).
Copy link
Collaborator

@reveloper reveloper Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of a "for example" structure, let's accurately specify public hosts. It may be a 2-row table HOST for the Testnet and HOST the Mainnet environments.
Screenshot 0007-12-08 at 15 09 09

- `<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": {}
}'
```
Copy link
Collaborator

@reveloper reveloper Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we specify the error codes related to API-KEYs here?

cc @kdimentionaltree

Loading