This page documents the token acquisition flows supported by the AuthenticationApiClient. The SDK provides multiple GetTokenAsync overloads that implement various OAuth2, OIDC, and Auth0-specific authentication flows. Each flow is designed for a specific use case, from standard web application authentication to passwordless and multi-factor scenarios.
For information about ID token validation performed after token acquisition, see ID Token Validation. For passwordless and device flow initiation, see Passwordless and Device Flows. For MFA-specific operations beyond token acquisition, see Multi-Factor Authentication.
The AuthenticationApiClient exposes token acquisition through method overloading on GetTokenAsync. All methods target the /oauth/token endpoint (except MFA challenge operations) and return an AccessTokenResponse or specialized response type.
| Flow Type | Request Model | Primary Use Case | Grant Type |
|---|---|---|---|
| Authorization Code | AuthorizationCodeTokenRequest | Web applications after redirect | authorization_code |
| Authorization Code + PKCE | AuthorizationCodePkceTokenRequest | Mobile/SPA applications | authorization_code |
| Client Credentials | ClientCredentialsTokenRequest | Machine-to-machine | client_credentials |
| Resource Owner | ResourceOwnerTokenRequest | Trusted applications with credentials | password or http://auth0.com/oauth/grant-type/password-realm |
| Refresh Token | RefreshTokenRequest | Token renewal | refresh_token |
| Passwordless Email | PasswordlessEmailTokenRequest | Email-based authentication | http://auth0.com/oauth/grant-type/passwordless/otp |
| Passwordless SMS | PasswordlessSmsTokenRequest | SMS-based authentication | http://auth0.com/oauth/grant-type/passwordless/otp |
| Device Authorization | DeviceCodeTokenRequest | Input-constrained devices | urn:ietf:params:oauth:grant-type:device_code |
| CIBA | ClientInitiatedBackchannelAuthorizationTokenRequest | Backchannel authentication | urn:openid:params:grant-type:ciba |
| MFA OOB | MfaOobTokenRequest | Out-of-band MFA verification | http://auth0.com/oauth/grant-type/mfa-oob |
| MFA OTP | MfaOtpTokenRequest | One-time password MFA | http://auth0.com/oauth/grant-type/mfa-otp |
| MFA Recovery Code | MfaRecoveryCodeRequest | MFA recovery | http://auth0.com/oauth/grant-type/mfa-recovery-code |
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs127-610 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs53-272
The following diagram illustrates how different request models are routed through the AuthenticationApiClient pipeline to the Auth0 /oauth/token endpoint.
Title: Token Request Pipeline
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs127-610 src/Auth0.AuthenticationApi/AuthenticationApiClient.cs740-769
Exchanges an authorization code obtained from /authorize redirect for tokens. This is the most common flow for traditional web applications.
Title: Authorization Code Exchange Sequence
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs127-149
Request Parameters:
ClientId: Application client ID src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs18Code: Authorization code from redirect src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs13RedirectUri: Must match authorization request src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs29ClientSecret: Optional, used for ID token verification and authentication src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs37ClientAssertionSecurityKey / ClientAssertionSecurityKeyAlgorithm: For JWT-based client authentication src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs42-47SigningAlgorithm: Algorithm for ID token validation src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs24Organization: Optional organization identifier for validation src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs56Key Features:
AssertIdTokenValid() src/Auth0.AuthenticationApi/AuthenticationApiClient.cs146Organization parameter provided src/Auth0.AuthenticationApi/Tokens/IdTokenClaimValidator.cs95-105Example Usage: tests/Auth0.AuthenticationApi.IntegrationTests/AccessTokenTests.cs125-140
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs127-149 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs53-60 src/Auth0.AuthenticationApi/Models/AuthorizationCodeRequestBase.cs1-57
Enhanced version of authorization code flow that uses Proof Key for Code Exchange (PKCE) for improved security, especially in public clients like mobile apps and SPAs.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs152-175
Request Parameters:
AuthorizationCodeTokenRequest parameters except ClientSecret.CodeVerifier: PKCE code verifier matching the code challenge src/Auth0.AuthenticationApi/AuthenticationApiClient.cs160Key Differences from Standard Authorization Code:
code_verifier in request body src/Auth0.AuthenticationApi/AuthenticationApiClient.cs160ApplyClientAuthentication src/Auth0.AuthenticationApi/AuthenticationApiClient.cs163Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs152-175 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs62-69
Machine-to-machine authentication where the application authenticates as itself rather than on behalf of a user. Returns only an access token (no ID token or refresh token).
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs178-196
Request Parameters:
ClientId: Application client ID src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs18ClientSecret or client assertion credentials src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs22-33Audience: Target API identifier (required) src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs13Organization: Optional organization scoping src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs47Organization Support: When Organization is specified, the resulting access token includes org_id and org_name claims tests/Auth0.AuthenticationApi.IntegrationTests/TokenTests.cs36-60
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs178-196 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs71-79 src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs1-48
Authenticates users directly with username and password. Should only be used by highly trusted applications.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs227-257
Grant Type Selection Logic:
src/Auth0.AuthenticationApi/AuthenticationApiClient.cs242
Forwarded-For Header: When ForwardedForIp is provided, adds auth0-forwarded-for header for rate limiting and anomaly detection src/Auth0.AuthenticationApi/AuthenticationApiClient.cs244
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs227-257 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs90-101 src/Auth0.AuthenticationApi/Models/ResourceOwnerTokenRequest.cs1-72
Obtains new tokens using a previously issued refresh token without re-authenticating the user.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs199-224
ID Token Validation: If the response includes a new ID token, validates it with organization claim checking src/Auth0.AuthenticationApi/AuthenticationApiClient.cs221
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs199-224 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs81-88 src/Auth0.AuthenticationApi/Models/RefreshTokenRequest.cs1-64
Exchanges a one-time code received via email for tokens.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs260-285
Request Body Construction:
grant_type: http://auth0.com/oauth/grant-type/passwordless/otp src/Auth0.AuthenticationApi/AuthenticationApiClient.cs266username: From request.Email src/Auth0.AuthenticationApi/AuthenticationApiClient.cs269realm: email src/Auth0.AuthenticationApi/AuthenticationApiClient.cs270otp: From request.Code src/Auth0.AuthenticationApi/AuthenticationApiClient.cs271Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs260-285 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs103-110
Exchanges a one-time code received via SMS for tokens.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs288-317
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs288-317 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs112-119
OAuth2 device authorization flow for input-constrained devices. Requires polling the token endpoint.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs320-342
Polling Strategy: Applications must poll this endpoint at intervals specified by StartDeviceFlowAsync() response src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs129-130
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs320-342 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs121-131
OpenID Connect backchannel authentication flow where authentication happens on a separate device/channel.
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs515-536
Client Authentication: CIBA requires client authentication, enforced by the requireSecret=true parameter in ApplyClientAuthentication src/Auth0.AuthenticationApi/AuthenticationApiClient.cs527
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs515-536 src/Auth0.AuthenticationApi/IAuthenticationApiClient.cs198-208
All token acquisition flows support two methods of client authentication: client secret and client assertion (JWT bearer).
Title: Client Authentication Logic
Implementation: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs740-769
Traditional OAuth2 client authentication using a shared secret.
Usage: Set ClientSecret property on request object src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs22-23
More secure authentication using a JWT signed with a private key.
Usage: Set ClientAssertionSecurityKey and ClientAssertionSecurityKeyAlgorithm on the request object src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs26-33
JWT Generation: Uses JwtTokenFactory to create a signed JWT with client_assertion_type set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer src/Auth0.AuthenticationApi/AuthenticationApiClient.cs759-763
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs740-769 src/Auth0.AuthenticationApi/Models/ClientCredentialsTokenRequest.cs1-48 tests/Auth0.AuthenticationApi.IntegrationTests/TokenTests.cs63-92
All token acquisition methods use the same endpoint, constructed during client initialization:
src/Auth0.AuthenticationApi/AuthenticationApiClient.cs61
The endpoint is stored as an instance field and reused across all token requests for efficiency src/Auth0.AuthenticationApi/AuthenticationApiClient.cs27
Sources: src/Auth0.AuthenticationApi/AuthenticationApiClient.cs27-61
Refresh this wiki