From ded2e020dc736a216968a569c368246f1ff48381 Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Mon, 1 Dec 2025 04:52:50 +0200 Subject: [PATCH 1/3] add api v2 auth details page --- docs.json | 1 + ecosystem/api/toncenter/v2-authentication.mdx | 68 +++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 ecosystem/api/toncenter/v2-authentication.mdx diff --git a/docs.json b/docs.json index 157573c33..09b8584d0 100644 --- a/docs.json +++ b/docs.json @@ -73,6 +73,7 @@ "expanded": true, "pages": [ "ecosystem/api/toncenter/get-api-key", + "ecosystem/api/toncenter/v2-authentication", { "group": "API v2", "openapi": { diff --git a/ecosystem/api/toncenter/v2-authentication.mdx b/ecosystem/api/toncenter/v2-authentication.mdx new file mode 100644 index 000000000..1cb38e8f7 --- /dev/null +++ b/ecosystem/api/toncenter/v2-authentication.mdx @@ -0,0 +1,68 @@ +--- +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, please follow [this guide](./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:///api/v2/getMasterchainInfo" \ + -H "X-API-Key: " +``` + +### Query parameter authentication + +Pass the key as a query parameter named `api_key`: + +```bash +curl "https:///api/v2/getMasterchainInfo?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:///api/v2/jsonRPC" \ + -H "Content-Type: application/json" \ + -H "X-API-Key: " \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "getMasterchainInfo", + "params": {} + }' +``` + +Or using the query parameter: + +```bash +curl "https:///api/v2/jsonRPC?api_key=" \ + -H "Content-Type: application/json" \ + -d '{ + "jsonrpc": "2.0", + "id": 1, + "method": "getMasterchainInfo", + "params": {} + }' +``` From 80aadba9a5fee7ee796a63ea7594a0ac2d25e6de Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Mon, 1 Dec 2025 04:55:26 +0200 Subject: [PATCH 2/3] fix linting --- ecosystem/api/toncenter/v2-authentication.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/ecosystem/api/toncenter/v2-authentication.mdx b/ecosystem/api/toncenter/v2-authentication.mdx index 1cb38e8f7..ab0364511 100644 --- a/ecosystem/api/toncenter/v2-authentication.mdx +++ b/ecosystem/api/toncenter/v2-authentication.mdx @@ -35,7 +35,6 @@ curl "https:///api/v2/getMasterchainInfo?api_key=" Both forms are equivalent. - ## JSON-RPC endpoints authentication Endpoint: `POST /api/v2/jsonRPC` From 3a885486484248a665640bf29cd5ca839667f05f Mon Sep 17 00:00:00 2001 From: laviniat1996 Date: Mon, 1 Dec 2025 05:17:15 +0200 Subject: [PATCH 3/3] address ai comments --- ecosystem/api/toncenter/v2-authentication.mdx | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/ecosystem/api/toncenter/v2-authentication.mdx b/ecosystem/api/toncenter/v2-authentication.mdx index ab0364511..3c05d797a 100644 --- a/ecosystem/api/toncenter/v2-authentication.mdx +++ b/ecosystem/api/toncenter/v2-authentication.mdx @@ -4,8 +4,10 @@ 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, please follow [this guide](./get-api-key). +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 | | ------- | -------- | ----------- | -------- | @@ -21,16 +23,21 @@ Only one of these is needed per request. Send the API key in the `X-API-Key` header: ```bash -curl "https:///api/v2/getMasterchainInfo" \ - -H "X-API-Key: " +curl "https:///api/v2/getMasterchainInfo" \ + -H "X-API-Key: " ``` +**Definitions:** + +- `` - The base URL of the TON Center API instance (`toncenter.com` for example). +- `` - 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:///api/v2/getMasterchainInfo?api_key=" +curl "https:///api/v2/getMasterchainInfo?api_key=" ``` Both forms are equivalent. @@ -42,7 +49,7 @@ Endpoint: `POST /api/v2/jsonRPC` The same API key rules apply. Example using header authentication: ```bash -curl "https:///api/v2/jsonRPC" \ +curl "https:///api/v2/jsonRPC" \ -H "Content-Type: application/json" \ -H "X-API-Key: " \ -d '{ @@ -56,7 +63,7 @@ curl "https:///api/v2/jsonRPC" \ Or using the query parameter: ```bash -curl "https:///api/v2/jsonRPC?api_key=" \ +curl "https:///api/v2/jsonRPC?api_key=" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0",