External Credentials Exchange

Server Authentication with External Credentials Exchange

Use the Bot Token Endpoint if your game has an account system that uniquely identifies users. It is simpler, requires no identity provider configuration, and is the recommended approach for most integrations.Use External Credentials Exchange only if you have a hard requirement for a server-side custom OIDC integration. If you don’t have a server-authoritative backend, use Public Client Integration instead.

Before using this method, you must configure your identity provider in the Developer Portal. Exchange the external provider’s token for a Discord access token from your game server:

# filepath: your_game/server/auth.py
import requests

def get_provisional_token(external_token: str):
  response = requests.post(
    'https://discord.com/api/v10/partner-sdk/token',
    json={
      'client_id': CLIENT_ID,
      'client_secret': CLIENT_SECRET,
      'external_auth_type': EXTERNAL_AUTH_TYPE,  # See External Auth Types
      'external_auth_token': external_token
    }
  )
  return response.json()

See the External Auth Types table for the full list of supported external_auth_type values.

External Credentials Exchange Response

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

If you are using OIDC, you may see a refresh_token in this response. Using it via the OAuth2 refresh_token grant is deprecated — re-authenticate using a fresh provider token instead. See Refreshing Access Tokens for details.

How the Flow Works

Once authentication is complete, you can use the access token as you would a full Discord user’s access token. See Managing Provisional 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

If you are using OIDC, you may encounter more specific errors:

Code	Meaning	Solution
530002	Invalid issuer	Verify the `iss` claim in your ID token exactly matches the issuer URL in your OIDC configuration
530003	Invalid audience	Verify the `aud` claim in your ID token includes the client ID in your OIDC configuration
530008	OIDC configuration not found	Verify your issuer URL is correct, accessible over HTTPS, and serves a valid discovery document without HTTP redirects
530009	OIDC JWKS not found	Verify your JWKS endpoint is accessible over HTTPS without HTTP redirects
530020	Invalid OIDC JWT token	Verify your ID token is properly signed and uses a supported algorithm
530027	Missing `kid` header	Ensure your ID token includes a `kid` (Key ID) header in the JWT header identifying the signing key

Next Steps

Configuring Identity Providers

Set up OIDC, Steam, EOS, and other providers, and review the OIDC requirements.

Managing Provisional Accounts

Refresh access tokens and set display names.

Need help? Join the Discord Developers Server 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

Change Log

Date	Changes
July 14, 2026	Split the provisional accounts guide into its own section
March 17, 2025	Initial release

Discord Social SDK

Core Concepts

Getting Started

Design Foundations

Provisional Accounts

Discord Account Linking

Friends & Relationships

Rich Presence & User Status

Game Invites

Direct Messages

Lobbies & Voice

How To

Server Authentication with External Credentials Exchange

External Credentials Exchange Response

How the Flow Works

Error Handling

Next Steps

Configuring Identity Providers

Managing Provisional Accounts

Change Log

​Server Authentication with External Credentials Exchange

​External Credentials Exchange Response

​How the Flow Works

​Error Handling

​Next Steps

Configuring Identity Providers

Managing Provisional Accounts

​Change Log

Server Authentication with External Credentials Exchange

External Credentials Exchange Response

How the Flow Works

Error Handling

Next Steps

Change Log