> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt) # Token API documentation for the FusionAuth Token OAuth2 endpoint. # Token This is an implementation of the Token endpoint as defined by the [IETF RFC 6749 Section 3.2](https://tools.ietf.org/html/rfc6749#section-3.2). ## Complete the Authorization Code Grant Request Authorization Code Grant : Exchange the Authorization Code for a Token If you will be using the Authorization Code grant, you will make a request to the Token endpoint to exchange the authorization code returned from the Authorize endpoint for an access token. POST/oauth2/token OpenAPI Spec ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Body Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is then required. Prior to version `1.3.1` this parameter was always required. `client_secret`StringoptionalAvailable since 1.5.0 The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `code`Stringrequired The authorization code returned on the `/oauth2/authorize` response. `code_verifier`StringoptionalAvailable since 1.8.0 The `code_verifier` parameter as described in the [Proof Key for Code Exchange by OAuth Public Clients (PKCE)](https://tools.ietf.org/html/rfc7636) specification. This parameter is required to complete this request when the **code\_challenge** parameter was provided on the initial Authorize request. `grant_type`Stringrequired The grant type to be used. This value must be set to `authorization_code` `redirect_uri`Stringrequired The URI to redirect to upon a successful request. This URI must have been configured previously in the FusionAuth Application OAuth configuration. See Applications in the FusionAuth User Guide for additional information on configuring the redirect URI. `resource`StringoptionalAvailable since 1.67.0 The URI of the target resource server, per [RFC 8707 (Resource Indicators for OAuth 2.0)](https://www.rfc-editor.org/rfc/rfc8707.html). To provide multiple URIs, pass each URI as a separate parameter with the same name. The following validation rules are applied in order; any failure returns `invalid_target` and the authorization code is immediately invalidated: 1. If at least one resource URI from the authorize request is still present in the application's **oauthConfiguration.authorizedResourceUris**, then at least one `resource` value is required here. 2. Each provided value must be present in the application's **oauthConfiguration.authorizedResourceUris**. 3. Each provided value must have also been present in the original authorize request. When a valid resource is resolved, the issued access token's `aud` claim is set to `["client_id", "https://resource1.example.com", ...]`. When no resource is involved, `aud` remains a plain string containing only the `client_id`. The validated resource URIs are also stored in the refresh token's `metaData.resources` field for use in subsequent refresh token grants. Example HTTP Request ```plaintext POST /oauth2/token HTTP/1.1 Host: piedpiper.fusionauth.io Content-Type: application/x-www-form-urlencoded Accept: */* Content-Length: 436 client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&code=+WYT3XemV4f81ghHi4V+RyNwvATDaD4FIj0BpfFC4Wzg&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fwww.piedpiper.com%2Flogin ``` ## Resource Owner Password Credentials Grant Request Resource Owner Password Credentials Grant : Exchange User Credentials for a Token If you will be using the Resource Owner Password Credential Grant, you will make a request to the Token endpoint to exchange the user's email and password for an access token. POST/oauth2/token OpenAPI Spec ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Body Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is then required. Prior to version `1.3.1` this parameter was always required. `client_secret`StringoptionalAvailable since 1.5.0 The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `grant_type`Stringrequired The grant type to be used. This value must be set to `password` `metaData.device.description`StringoptionalAvailable since 1.20.1 A human readable description of the device used during login. This metadata is used to describe the refresh token that may be generated for this login request. For example: > Erlich's iPhone `metaData.device.name`StringoptionalAvailable since 1.20.1 A human readable description of the device used during login. This metadata is used to name the refresh token that may be generated for this login request. For example: > iOS Safari `metaData.device.type`StringoptionalAvailable since 1.20.1 The type of device represented by the `device` parameter. This metadata is used to describe the type of device represented by the refresh token that may be generated for this login request. Prior to version 1.46.0, this value was restricted to the following types: * `BROWSER` * `DESKTOP` * `LAPTOP` * `MOBILE` * `OTHER` * `SERVER` * `TABLET` * `TV` * `UNKNOWN` In version `1.46.0` and beyond, this value can be any string value you'd like, have fun with it! `username`Stringrequired The login identifier of the user. The login identifier can be either the `email` or the `username`. `password`Stringrequired The user's password. `scope`Stringoptional The optional scope you are requesting during this grant. This parameter may contain multiple space separated scopes. For example, the value of `openid offline_access` provides two scopes on the request. Available scopes: * `openid` - This scope is used to request an `id_token` be returned in the response * `offline_access` - This scope scope is used to request a `refresh_token` be returned in the response `user_code`StringoptionalAvailable since 1.11.0 The end-user verification code. This parameter is required on requests implementing the user-interaction of the Device Authorization Grant flow. Example HTTP Request ```plaintext POST /oauth2/token HTTP/1.1 Host: piedpiper.fusionauth.io Content-Type: application/x-www-form-urlencoded Accept: */* Content-Length: 436 client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&grant_type=password&loginId=bishop%piedpiper.com&password=Setec+Astronomy ``` ## Complete the Device Authorization Grant Request version This API has been available since 1.11.0 This is the Device Access Token Request portion of the [Device Authorization Grant Specification](https://tools.ietf.org/html/rfc8628#section-3.4). POST/oauth2/token OpenAPI Spec ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Body Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is then required. `client_secret`Stringoptional The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `device_code`Stringrequired `grant_type`Stringrequired The grant type to be used. This value must be set to `urn:ietf:params:oauth:grant-type:device_code` Example HTTP Request ```plaintext POST /oauth2/token HTTP/1.1 Host: piedpiper.fusionauth.io Content-Type: application/x-www-form-urlencoded Accept: */* Content-Length: 166 client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code ``` ### Response The following response applies to the [Complete the Authorization Code Grant Request](#complete-the-authorization-code-grant-request), [Refresh Token Grant Request](#refresh-token-grant-request) and [Complete the Device Authorization Grant Request](#complete-the-device-authorization-grant-request) examples. *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the [OAuth Error section](https://fusionauth.io/docs/apis/oauth/oauth-error.md) of the API documentation. | | 401 | The client could not be verified. Verify your `client_id` and `client_secret` are valid and authorized for this request. | | 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | ### Response Body `access_token`String The OAuth access token as described by [RFC 6749 Section 1.4](https://tools.ietf.org/html/rfc6749#section-1.4). See the [OAuth Tokens](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/tokens.md#access-token) documentation for more information. `expires_in`Integer The time in seconds the token will expire from the time the response was generated. `id_token`String The OpenID Id Token. This token is represented as a JSON Web Token (JWT). See the [OAuth Tokens](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/tokens.md#id-token) documentation for more information. This field will be returned in the response when `openid` scope was requested. `refresh_token`String The refresh token as described by [RFC 6749 Section 1.5](https://tools.ietf.org/html/rfc6749#section-1.5) This field will be returned in the response when `offline_access` scope was requested unless refresh tokens have been disabled for this application. Whether a refresh token is allowed for an application can be controlled by the **oauthConfiguration.generateRefreshTokens** field in the [Application API](https://fusionauth.io/docs/apis/applications.md) or the `Generate refresh tokens` toggle in the FusionAuth admin UI. `refresh_token_id`UUIDAvailable since 1.37.0 The unique Id of the refresh token. This Id can be used to retrieve or revoke a specific refresh token using the [Refresh Token API](https://fusionauth.io/docs/apis/jwt.md). This field will be returned when the `offline_access` scope was requested and refresh tokens are allowed for this application. Whether a refresh token is allowed for an application can be controlled by the **oauthConfiguration.generateRefreshTokens** field in the [Application API](https://fusionauth.io/docs/apis/applications.md) or the `Generate refresh tokens` toggle in the FusionAuth admin UI. `scope`StringAvailable since 1.5.0 The space-separated list of scopes allowed by the user during the grant which generated this access token. This will only be present for Authorization Code and Password grants. `token_type`String The token type as defined by [RFC 6749 Section 7.1](https://tools.ietf.org/html/rfc6749#section-7.1). This value will be `Bearer` or `DPoP` if a [DPoP Proof](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/dpop.md) was provided. `userId`String The unique Id of the user that has been authenticated. This user Id may be used to retrieve the entire user object using the /api/user API. *Example JSON Response* ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo", "expires_in": 3600, "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo", "refresh_token": "ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ", "refresh_token_id": "4c8927f1-95cd-4bf8-9534-066389ffff5e", "scope": "openid offline_access", "token_type": "Bearer", "userId": "3b6d2f70-4821-4694-ac89-60333c9c4165" } ``` ## Refresh Token Grant Request If you will be using the Refresh Token Grant, you will make a request to the Token endpoint to exchange the user's refresh token for an access token. note In version `1.50.0` and later a refresh token containing unknown scopes will be revoked when used for a Refresh Token Grant if the **oauthConfiguration.unknownScopePolicy** value of the associated application is `Reject`. POST/oauth2/token OpenAPI Spec ### Request Cookies `access_token`StringoptionalAvailable since 1.16.0 The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the **original** field. If both the cookie and request parameter are provided, the cookie will take precedence. ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Parameters Ensure you are sending these parameters as form encoded data in the request body, do not send these parameters in a query string. `access_token`StringoptionalAvailable since 1.16.0 The previously issued encoded access token. When provided on the request, this value will be relayed in the related JWT Refresh webhook event within the **original** field. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Application in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is then required. Prior to version `1.3.1` this parameter was always required. `client_secret`StringoptionalAvailable since 1.5.0 The client secret. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `expires_in`IntegeroptionalAvailable since 1.59.0 The expiration time, in seconds, for the access and Id tokens (if the `openid` scope was included) that will be returned in the response. When provided on the request, this value will override the default TTL, provided it is less than the default value. The default TTL is taken from **application.jwtConfiguration.timeToLiveInSeconds** if it is set there, otherwise it is taken from **tenant.jwtConfiguration.timeToLiveInSeconds**. `grant_type`Stringrequired The grant type to be used. This value must be set to `refresh_token` `refresh_token`Stringrequired The refresh token that you would like to use to exchange for an access token. `resource`StringoptionalAvailable since 1.67.0 The URI of the target resource server, per [RFC 8707 (Resource Indicators for OAuth 2.0)](https://www.rfc-editor.org/rfc/rfc8707.html). To provide multiple URIs, pass each URI as a separate parameter with the same name. Behavior depends on the application's **oauthConfiguration.authorizedResourceUris**: * When **oauthConfiguration.authorizedResourceUris** is empty, this parameter is silently ignored. * When omitted and **oauthConfiguration.authorizedResourceUris** is non-empty, the resource URIs stored in the refresh token's `metaData.resources` from the original authorization are automatically applied to the new access token. * When provided, each value must be present in both the application's **oauthConfiguration.authorizedResourceUris** and the refresh token's `metaData.resources` (i.e. must be a subset of what was authorized originally). Any invalid value returns `invalid_target`. The `aud` claim follows the same rules as the authorization code exchange: an array `["client_id", "https://resource1.example.com", ...]` when resources are active, or a plain string `client_id` when they are not. `scope`Stringoptional This parameter is optional and if omitted, the same scope requested during the authorization request will be used. If provided, the scopes must be a space-delimited subset of those requested during the initial authorization request. The refresh token maintains the set of scopes from the initial authorization request even if a subset of scopes is requested during a Refresh Token Grant. Prior to version `1.50.0` the scopes must match those requested during the initial authorization request if provided. `user_code`StringoptionalAvailable since 1.11.0 The end-user verification code. This code is required if using this endpoint to approve the Device Authorization. Example HTTP Request ```plaintext POST /oauth2/token HTTP/1.1 Host: piedpiper.fusionauth.io Content-Type: application/x-www-form-urlencoded Cookie: access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IkFuYV91STRWbWxiMU5YVXZ0cV83SjZKZFNtTSJ9.eyJleHAiOjE1ODgzNTM0NjAsImlhdCI6MTU4ODM1MzQwMCwiaXNzIjoiZnVzaW9uYXV0aC5pbyIsInN1YiI6IjAwMDAwMDAwLTAwMDAtMDAwMS0wMDAwLTAwMDAwMDAwMDAwMCIsImF1dGhlbnRpY2F0aW9uVHlwZSI6IlBBU1NXT1JEIiwiZW1haWwiOiJ0ZXN0MEBmdXNpb25hdXRoLmlvIiwiZW1haWxfdmVyaWZpZWQiOnRydWUsInByZWZlcnJlZF91c2VybmFtZSI6InVzZXJuYW1lMCJ9.ZoIHTo3Pv0DpcELeX_wu-ZB_rd988jefZc2Ozu9_p59kttwqMm5PV8IDbgxJw9xcq9TFoNG8e_B6renoc11JC54UbiyeXBjF7EH01n9LDz-zTGqu9U72470Z4E7IPAHcyvJIBx4Mp9sgsEYAUm9Tb8ChudqNHhn6ZnXYI7Sew7CtGlu62f10wdBYGX0soYARHBv9CwhJC3-gsD2HLmqHAP_XhrpaYPNr5EAvmCHlM-JlTiEQ9bXwSc4gv-XbPQWamwy8Kcdb-g0EEAml_dC_b2CduwwYg0EoPQB3tQxzTUQzADi7K6q0CtQXv2_1VrRi6aQ4lt7v7t-Na39wGry_pA Accept: */* Content-Length: 436 client_id=3c219e58-ed0e-4b18-ad48-f4f92793ae32&grant_type=refresh_token&refresh_token=ze9fi6Y9sMSf3yWp3aaO2w7AMav2MFdiMIi2GObrAi-i3248oo0jTQ ``` ### Response *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the [OAuth Error section](https://fusionauth.io/docs/apis/oauth/oauth-error.md) of the API documentation. | | 401 | The client could not be verified. Verify your `client_id` and `client_secret` are valid and authorized for this request. | | 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | ### Response Body `access_token`String The OAuth access token as described by [RFC 6749 Section 1.4](https://tools.ietf.org/html/rfc6749#section-1.4). See the [OAuth Tokens](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/tokens.md#access-token) documentation for more information. `expires_in`Integer The time in seconds the token will expire from the time the response was generated. `id_token`String The OpenID Id Token. This token is represented as a JSON Web Token (JWT). See the [OAuth Tokens](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/tokens.md#id-token) documentation for more information. This field will be returned in the response when `openid` scope was requested during the initial authentication request when the refresh token was generated. `token_type`String The token type as defined by [RFC 6749 Section 7.1](https://tools.ietf.org/html/rfc6749#section-7.1). This value will be `Bearer` or `DPoP` if a [DPoP Proof](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/dpop.md) was provided. `userId`String The unique Id of the user that has been authenticated. This user Id may be used to retrieve the entire user object using the /api/user API. *Example JSON Response* ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo", "expires_in": 3600, "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo", "token_type": "Bearer", "userId": "3b6d2f70-4821-4694-ac89-60333c9c4165" } ``` ## Client Credentials Grant Request This feature is only available in paid plans. To learn more, see [our pricing page](https://fusionauth.io/pricing.md). version This functionality has been available since version 1.26. If you will be using the Client Credentials grant, you will make a request to the Token endpoint to exchange the client credentials for an access token. POST/oauth2/token OpenAPI Spec ### Request Headers `Authorization`Stringoptional This header is optional if you have provided the **client\_id** in the request body. The **client\_secret** may be provided in the request body as well, but may be optional depending on the OAuth grant and configuration settings. If provided, the **client\_secret** must be valid. Please see [the Client Secret section](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. If providing client authentication using the [Basic Authentication Scheme](https://tools.ietf.org/html/rfc7617#section-2) authorization header, the value is created by taking the `clientId` and `clientSecret` properties defined in the Application OAuth Configuration and concatenating them together using a `:` character. Here is an example of these two values concatenated. ```plaintext 463228ba-868a-462d-b86f-6096af2d70e0:salkjdsoiu32ldslnkasglhilkja892 ``` This value is then Base64 encoded and prepended with the string `Basic` to denote the schema type. The following is an example Authorization header using the example concatenation above. ```plaintext Authorization: Basic NDYzMjI4YmEtODY4YS00NjJkLWI4NmYtNjA5NmFmMmQ3MGUwOnNhbGtqZHNvaXUzMmxkc2xua2FzZ2xoaWxramE4OTI= ``` The above concatenation example and resulting Authorization header are simply for demonstration. Your actual header value will be different. `Content-Type`Stringrequired This value must be set to `application/x-www-form-urlencoded`. ### Request Parameters Ensure you are sending these parameters as form encoded data in the request body. Do not send these parameters in a query string or as JSON. `client_id`Stringoptional The unique client identifier. The client Id is the Id of the FusionAuth Entity in which you are attempting to authenticate. This parameter is optional when the `Authorization` header is provided. When the `Authorization` header is not provided, this parameter is required. `client_secret`Stringoptional The client secret of the Entity. This parameter is optional when the `Authorization` header is provided. Please see the [the Client Secret table](https://fusionauth.io/docs/apis/oauth/client-secret.md) for more details. `grant_type`Stringrequired The grant type to be used. This value must be set to `client_credentials` `scope`Stringoptional This parameter is optional. This is a space delimited set of the requested scopes for this grant request. You will typically provide a scope specifying the target entity: ```plaintext target-entity:92dbded-30af-4149-9c61-b578f2c72600 ``` You may provide append a comma separated list of permissions as well: ```plaintext target-entity:92dbded-30af-4149-9c61-b578f2c72600:read,write ``` You may combine multiple entities and permissions in the same **scope** parameter: ```plaintext target-entity:92dbded-30af-4149-9c61-b578f2c72600:read,write target-entity:119a84d9-06c5-4d1f-a0d4-a60490b70ac5:read ``` Permissions associated with the grant from the target entity to the recipient entity will be available in the `permissions` claim in the token. If specific permissions are requested, the recipient entity must have previously been granted all of those permissions for a successful access request. If specific permissions are requested, only the requested permissions will be in the `permissions` claim, otherwise all permissions will be available in that claim. Example HTTP Request ```plaintext POST /oauth2/token HTTP/1.1 Host: piedpiper.fusionauth.io Authorization: Basic MDkyZGJkZWQtMzBhZi00MTQ5LTljNjEtYjU3OGYyYzcyZjU5OitmY1hldDlJdTJrUWk2MXlXRDlUdTRSZVoxMTNQNnlFQWtyMzJ2NldLT1E9 Content-Type: application/x-www-form-urlencoded Accept: */* Content-Length: 436 grant_type=client_credentials &scope=target-entity%3Ae13365f1-a270-493e-bd1b-3d239d753d53%3Aread ``` ### Response *Response Codes* | Code | Description | | --- | --- | | 200 | The request was successful. | | 400 | The request was invalid and/or malformed. The response will contain a JSON message with the specific errors. The error response JSON is covered in the [OAuth Error section](https://fusionauth.io/docs/apis/oauth/oauth-error.md) of the API documentation. | | 401 | The client could not be verified. Verify your `client_id` and `client_secret` are valid and authorized for this request. | | 500 | There was a FusionAuth internal error. A stack trace is provided and logged in the FusionAuth log files. | | 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. | ### Response Body `access_token`String The OAuth access token as described by [RFC 6749 Section 1.4](https://tools.ietf.org/html/rfc6749#section-1.4). See the [OAuth Tokens](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/tokens.md#access-token) documentation for more information. `expires_in`Integer The time in seconds the token will expire from the time the response was generated. `scope`String The scope value from the request. `token_type`String The token type. This value will be `Bearer` or `DPoP` if a [DPoP Proof](https://fusionauth.io/docs/lifecycle/authenticate-users/oauth/dpop.md) was provided. ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjM0ZjE3ZDdiNzIifQ.eyJhdWQiOiJlMTMzNjVmMS1hMjcwLTQ5M2UtYmQxYi0zZDIzOWQ3NTNkNTMiLCJleHAiOjE2MjAyMzc3MjksImlhdCI6MTYyMDIzNDEyOSwiaXNzIjoiaHR0cHM6Ly9sb2NhbC5mdXNpb25hdXRoLmlvIiwic3ViIjoiMjkzNGY0MWYtZDI3Ny00YTMyLWIwZDUtMTZlNDdkYWQ5NzIxIiwianRpIjoiMGIwMmY1MDktYmNmMy00YjhkLWEzZGItMDNmOThhY2U5ZDlmIiwicGVybWlzc2lvbnMiOnsiZTEzMzY1ZjEtYTI3MC00OTNlLWJkMWItM2QyMzlkNzUzZDUzIjpbInJlYWQiXX19.1BR367JxpWp33HuHEY0_zHuVDmnYrgi7CzzjlIYwtqQ", "expires_in": 3599, "scope": "target-entity:e13365f1-a270-493e-bd1b-3d239d753d53:read", "token_type": "Bearer" } ```