> For the complete documentation index, see [llms.txt](https://ton-play-1.gitbook.io/ton-play-1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ton-play-1.gitbook.io/ton-play-1/digital-assets-api/auth-api.md).

# Auth API

You can authorize your Telegram users on TON Play and get [User JWT](/ton-play-1/digital-assets-api/authentication.md)

{% hint style="success" %}
**API Key is required for all Public API requests.**\
[**`bot_key`**](/ton-play-1/digital-assets-api/api-key.md#bot-key) **is required for the upcoming request**
{% endhint %}

## Telegram user authorization on TON Play

<mark style="color:green;">`POST`</mark> `https://external.api.tonplay.io/x/auth/v2/login/tg`

#### Headers

| Name                                             | Type   | Description |
| ------------------------------------------------ | ------ | ----------- |
| X-Auth-Tonplay<mark style="color:red;">\*</mark> | String | API Key     |

#### Request Body

| Name                                       | Type   | Description                                                                       |
| ------------------------------------------ | ------ | --------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark>       | long   | User telegram id                                                                  |
| username                                   | String | User telegram username                                                            |
| first\_name                                | String | User telegram first name                                                          |
| last\_name                                 | String | User telegram last name                                                           |
| hash<mark style="color:red;">\*</mark>     | String | A payload hash calculated using the user data, excluding hash and bot\_key fields |
| bot\_key<mark style="color:red;">\*</mark> | String | Secret key recieved from TON Play                                                 |

{% tabs %}
{% tab title="200: OK " %}
{% code overflow="wrap" %}

```json
{
    "token": "User JWT"
}
```

{% endcode %}
{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="500: Internal Server Error " %}

```json
{
    "timestamp": "2022-12-13T03:30:25.253+00:00",
    "path": "/x/auth/v1/game",
    "status": 500,
    "error": "Internal Server Error",
    "requestId": "d3341509-123683"
}
```

{% endtab %}
{% endtabs %}

Add [User JWT](/ton-play-1/digital-assets-api/authentication.md) to your game link: [https://game.com?token=jwtToken](<https://game.com?token=jwtTokenTutBudet &#xA;>)

<details>

<summary>Example</summary>

{% code overflow="wrap" %}

```uri
https://play.zeya.io/?token=eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIwZDljM2UzZjIzYzI4Zjk2YWFlNTQ2NGI3YTdhNTU5OTU0MWQyOWFmZDJmMWNkMDY1OGQ3YjJlZmEwMmRmZTE0IiwiaXNUZXN0IjpmYWxzZSwiaXNzIjoiaHR0cHM6XC9cL29hLnRvbnBsYXkuaW8iLCJnYW1lS2V5IjoiRFptclZrMW1KNSIsImV4cCI6MTY3OTY0ODAyOSwidG9rZW5fdHlwZSI6IkdBTUUiLCJpYXQiOjE2NzEwMDgwMjksImF1dGhvcml0aWVzIjpbIlJPTEVfVVNFUiJdLCJ0ZWxlZ3JhbUlkIjo1NDM4MjQyMjM4LCJ1c2VybmFtZSI6InNlbnNodV8zODIxNjEwOSJ9.hAjaroTO8ZT67FjtnywkvtfDgf65-cJSSUxp551_6u9KkaOaWwzJxHNpjaW7qOpf_auPaJVbMcP0G6ot84zLAjYTjCVsDUjg1PACeF2_H_0v9RKtUGk5QIu12O9VwVL_jF4FCtE8ypsnG_Q4iBHUb1XTPcSa3s0X2w8ZyB8KVn9MtC9YNhTTgyX3HfYZ7hmXB698wXqSAWGU_7MWjKu_pBuWIq-eK4wSBybkl9OlDVGQ_unQdhlucRxoGFKdQJBsOnNf5QD8A7v6mNtJYDUiW0B8h20Q0mK6zvyv0Kznt2LsxF3xXYSAts28LV1qKwsYatPoZ1iDK61MhYftPGjsog
```

{% endcode %}

</details>

### **How to calculate `hash` in the payload body?**

`Hash` is the hexadecimal representation of the [HMAC-SHA-256](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) signature of the **data-check-string** with the [SHA256](https://en.wikipedia.org/wiki/SHA-2) hash of the bot token (given by @BotFather) used as a secret key.

**data-check-string** is a concatenation of all received fields, sorted in alphabetical order in the format `key=<value>` with a [line feed](https://en.wikipedia.org/wiki/Newline) character ('\n') used as a separator – e.g.,

&#x20;'`auth_date=<auth_date>\nfirst_name=<first_name>\nid=<id>\nusername=<username>'`.

The full check might look like this:

```
data_check_string = ...
secret_key = SHA256(<bot_token>)
if (hex(HMAC_SHA256(data_check_string, secret_key)) == hash) 
{
  // request is valid
}
```

#### Hash calculation example

{% tabs %}
{% tab title="TypeScript" %}

```typescript
  import { HmacSHA256, enc, SHA256 } from "crypto-jstype
  
  function getParamsHash(paramsList: string[], botToken: string): string {
    const secretKey = SHA256(enc.Utf8.parse(botToken));
    const dataCheckString = paramsList.sort().join("\n");
    const hmac = HmacSHA256(dataCheckString, secretKey);
    return hmac.toString(enc.Hex).toLowerCase();
  }
```

{% endtab %}

{% tab title="C#" %}

```csharp
using System.Security.Cryptography; 
using System.Text;

public class APITonPlayTelegramLogin {
    public static string GetParamsHash(List<string> paramsList, string botToken) {
        string hash;
        byte[] secretKeyInBytes;
        
        paramsList.Sort((a, b) => a.CompareTo(b));
        string dataCheckString = string.Join("\n", paramsList);
        byte[] dataCheckInBytes = Encoding.UTF8.GetBytes(dataCheckString);
    
        using (SHA256 mySHA256 = SHA256.Create()) {
            byte[] botTokenBytes = Encoding.ASCII.GetBytes(botToken);
            secretKeyInBytes = mySHA256.ComputeHash(botTokenBytes);
        }
    
        using (HMACSHA256 hmac = new HMACSHA256(secretKeyInBytes)) {
            byte[] HMACSHA256DataCheck = hmac.ComputeHash(dataCheckInBytes);
            hash = Convert.ToHexString(HMACSHA256DataCheck);
        }
    
        return hash.ToLower();
    }
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Check your hash implementation</summary>

data-check-string:

```
first_name=John
id=0
last_name=Gamer
username=JohnGamer
```

bot\_token:

```
6003856761:AAHYYNJtsYfwBMb1ozzZ5PALbAL8mAMvUuQ
```

hash:

```
008b771d96ec1745d327fcd90510d2f8bef2aeb51836583090e70e9395d03258
```

</details>

List of samples: <https://gist.github.com/anonymous/6516521b1fb3b464534fbc30ea3573c2>