> ## 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.
# External Credentials Exchange
> Exchange an external provider token (OIDC, Steam, EOS, and more) server-side to create a provisional account.
export const WrenchIcon = props => ;
export const UserPlatformIcon = props => ;
## Server Authentication with External Credentials Exchange
**Use the [Bot Token Endpoint](/developers/discord-social-sdk/development-guides/provisional-accounts/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](/developers/discord-social-sdk/development-guides/provisional-accounts/public-client) instead.
Before using this method, you must [configure your identity provider](/developers/discord-social-sdk/development-guides/provisional-accounts/identity-providers) in the Developer Portal. Exchange the external provider's token for a Discord access token from your game server:
```python theme={"system"}
# 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](/developers/discord-social-sdk/development-guides/provisional-accounts/identity-providers#external-auth-types) table for the full list of supported `external_auth_type` values.
#### External Credentials Exchange Response
```python theme={"system"}
{
"access_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](/developers/discord-social-sdk/development-guides/provisional-accounts/managing-accounts#refreshing-access-tokens) for details.
### How the Flow Works
```mermaid theme={"system"}
sequenceDiagram
autonumber
actor P as Player
participant Prov as External Provider (OIDC, Steam, EOS)
participant G as Your Game Server
participant D as Discord API
P->>Prov: Authenticate
Prov-->>G: External auth token
G->>D: POST /partner-sdk/token { client_id, client_secret, external_auth_type, external_auth_token }
alt No account for identity
D->>D: Create provisional account
D-->>G: 200 { access_token, id_token, ... }
else Provisional account exists
D-->>G: 200 { access_token, id_token, ... }
else Full Discord account exists
D-->>G: Error 530010 (use OAuth2 flow)
end
```
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 |
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
}>
Set up OIDC, Steam, EOS, and other providers, and review the OIDC requirements.
}>
Refresh access tokens and set display names.
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 the provisional accounts guide into its own section |
| March 17, 2025 | Initial release |