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.

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:

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.

Query parameter authentication

Pass the key as a query parameter named api_key:

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:

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:

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