> ## Documentation Index
> Fetch the complete documentation index at: https://docs.discord.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bot Token Endpoint

> Create provisional accounts server-side from your game's own unique user IDs using your application's bot token.

export const SlashBoxIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" fill-rule="evenodd" d="M5 2a3 3 0 0 0-3 3v14a3 3 0 0 0 3 3h14a3 3 0 0 0 3-3V5a3 3 0 0 0-3-3H5Zm12.79 3.37a.25.25 0 0 0-.22-.37h-3.13a.75.75 0 0 0-.66.38L6.21 18.63c-.1.16.03.37.22.37h3.13c.27 0 .52-.14.66-.38l7.57-13.25Z" clip-rule="evenodd" /></svg>;

export const LinkIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" d="M16.32 14.72a1 1 0 0 1 0-1.41l2.51-2.51a3.98 3.98 0 0 0-5.62-5.63l-2.52 2.51a1 1 0 0 1-1.41-1.41l2.52-2.52a5.98 5.98 0 0 1 8.45 8.46l-2.52 2.51a1 1 0 0 1-1.41 0ZM7.68 9.29a1 1 0 0 1 0 1.41l-2.52 2.51a3.98 3.98 0 1 0 5.63 5.63l2.51-2.52a1 1 0 0 1 1.42 1.42l-2.52 2.51a5.98 5.98 0 0 1-8.45-8.45l2.51-2.51a1 1 0 0 1 1.42 0Z" /><path fill="currentColor" d="M14.7 10.7a1 1 0 0 0-1.4-1.4l-4 4a1 1 0 1 0 1.4 1.4l4-4Z" /></svg>;

export const WrenchIcon = props => <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none"><path fill="currentColor" d="M7.8 15.77c.7.43 1.2 1.14 1.2 1.96V21a1 1 0 0 0 1 1h4a1 1 0 0 0 1-1v-3.27c0-.82.5-1.53 1.2-1.96a8.06 8.06 0 0 0 .12-13.63c-.6-.39-1.32.09-1.32.8v5.98a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1V2.94c0-.71-.72-1.19-1.32-.8a8.06 8.06 0 0 0 .12 13.63Z" /></svg>;

## Server Authentication with Bot Token Endpoint

<Tip>
  This is the preferred method of authentication. It ends up being the simplest and most flexible choice for most
  provisional account integrations.
</Tip>

Use the Bot Token Endpoint if your game has an account system which uniquely identifies users.

You pass your account system's unique ID for the user, and Discord returns an access token — creating a provisional account for that identity if one does not already exist.

No identity provider configuration is required for this method.

If you have a hard requirement for a turnkey OIDC integration, see [External Credentials Exchange](/developers/discord-social-sdk/development-guides/provisional-accounts/external-credentials-exchange); if you don't have a backend, see [Public Client Integration](/developers/discord-social-sdk/development-guides/provisional-accounts/public-client).

<Warning>
  Your bot token is a privileged secret — it must stay on your backend and **never ship in the game client**. The client receives only the provisional `access_token` your backend returns. See [How the Integration Fits Together](#how-the-integration-fits-together) for the full flow.
</Warning>

### Server: Create the Provisional Token

Your backend exchanges the player's identity for a Discord access token. Keep this call and your bot token on the
server, exposed to the client through your own authenticated endpoint:

```python theme={"system"}
# filepath: your_game/server/auth.py
import requests
from models import GameAccount

def get_provisional_token(game_account: GameAccount):
  response = requests.post(
    'https://discord.com/api/v10/partner-sdk/token/bot',
    headers={
      'Content-Type': 'application/json',
      'Authorization': 'Bot <BOT_TOKEN>' # your application's bot token
    },
    json={
      'external_user_id': game_account.id,       # your account system's unique id
      'preferred_global_name': game_account.display_name, # your account system's display name for the user
    }
  )
  return response.json()
```

#### Bot Token Endpoint Response

```python theme={"system"}
{
  "access_token": "<access token>",
  "id_token": "<id token>",
  "token_type": "Bearer",
  "expires_in": 604800,
  "scope": "sdk.social_layer"
}
```

### Client: Connect With the Token

The game client receives the `access_token` from your backend — it never sees the bot token — and passes it straight to the SDK. Set your application ID, call [`Client::UpdateToken`] with the token as a `Bearer` token, then [`Client::Connect`]:

```cpp theme={"system"}
// filepath: your_game/client/connect.cpp
// `accessToken` was returned by YOUR backend, not requested directly from Discord.
client->SetApplicationId(DISCORD_APPLICATION_ID);

client->UpdateToken(discordpp::AuthorizationTokenType::Bearer, accessToken,
    [client](discordpp::ClientResult result) {
      if (result.Successful()) {
        client->Connect();
      } else {
        std::cerr << "Failed to update token: " << result.Error() << '\n';
      }
    });
```

### How the Integration Fits Together

Because your bot token never reaches the client, the client can't call Discord's bot token endpoint directly. Instead, your server brokers the request:

1. The player signs in with your own account system, as they normally would.
2. The game client asks **your backend** for a Discord provisional token.
3. Your backend calls Discord's `/partner-sdk/token/bot` endpoint — authenticated with your bot token — passing the player's `external_user_id` (and optional `preferred_global_name`), and returns the resulting `access_token` to the client.
4. The client hands that token to the SDK with [`Client::UpdateToken`] and calls [`Client::Connect`].

```mermaid theme={"system"}
sequenceDiagram
    autonumber
    actor P as Player
    participant C as Game Client (SDK)
    participant B as Your Game Backend
    participant D as Discord API

    P->>C: Sign in with your account system
    C->>B: Request a Discord provisional token<br/>(authenticated with your own session)
    Note over B: Your bot token lives only here
    B->>D: POST /partner-sdk/token/bot<br/>Authorization: Bot <token><br/>{ external_user_id, preferred_global_name }
    alt No account for external_user_id
        D->>D: Create provisional account
        D-->>B: 200 { access_token, id_token, ... }
    else Provisional account exists
        D-->>B: 200 { access_token, id_token, ... }
    else Full Discord account exists
        D-->>B: Error 530010 (use OAuth2 flow)
    end
    B-->>C: access_token
    C->>D: Client::UpdateToken(Bearer, access_token)
    C->>D: Client::Connect()
    D-->>C: Connected (status: Ready) — ready to use Social SDK features
```

Once authentication is complete, you can use the access token as you would a full Discord user's access token. See [Managing Provisional Accounts](/developers/discord-social-sdk/development-guides/provisional-accounts/managing-accounts) for token refresh, storage, and display names.

## Error Handling

Common error codes and solutions when creating a provisional account:

| Code   | Meaning                      | Solution                                                                    |
| ------ | ---------------------------- | --------------------------------------------------------------------------- |
| 530000 | Application not configured   | Contact Discord support to enable provisional accounts for your application |
| 530001 | Expired ID token             | Request a new token from your identity provider                             |
| 530004 | Token too old                | Request a new token (tokens over 1 week old are rejected)                   |
| 530006 | Username generation failed   | Retry the operation (temporary error)                                       |
| 530007 | Invalid client secret        | Verify or regenerate your client secret in the Developer Portal             |
| 530010 | User account non-provisional | User already linked to Discord account - use standard OAuth2 flow           |

***

## Next Steps

<CardGroup cols={3}>
  <Card title="Managing Provisional Accounts" href="/developers/discord-social-sdk/development-guides/provisional-accounts/managing-accounts" icon={<WrenchIcon />}>
    Refresh access tokens and set display names.
  </Card>

  <Card title="Merging Accounts" href="/developers/discord-social-sdk/development-guides/provisional-accounts/merging-accounts" icon={<LinkIcon />}>
    Merge a provisional account into a full Discord account.
  </Card>

  <Card title="Unmerging Accounts" href="/developers/discord-social-sdk/development-guides/provisional-accounts/unmerging-accounts" icon={<SlashBoxIcon />}>
    Sever the link between a Discord account and a provisional account.
  </Card>
</CardGroup>

Need help? Join the [Discord Developers Server](https://discord.gg/discord-developers) and share questions in the `#social-sdk-dev-help` channel for support from the community.

If you encounter a bug while working with the Social SDK, please report it here:  [https://dis.gd/social-sdk-bug-report](https://dis.gd/social-sdk-bug-report)

***

## Change Log

| Date           | Changes                                                            |
| -------------- | ------------------------------------------------------------------ |
| July 14, 2026  | Split into its own page with the client-to-server integration flow |
| March 17, 2025 | Initial release                                                    |

[`Client::Connect`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a873a844c7c4c72e9e693419bb3e290aa

[`Client::UpdateToken`]: https://discord.com/developers/docs/social-sdk/classdiscordpp_1_1Client.html#a606b32cef7796f7fb91c2497bc31afc4