OAuth - Token Endpoint
Table of Contents
1 - About
The token endpoint is an authorization endpoint used by the client to obtain an access token by presenting its:
- or refresh token.
The token endpoint is used with every authorization grant except for the implicit grant type (since an access token is issued directly).
A single token endpoint may issue access tokens accepted by multiple resource servers.
2 - Articles Related
3 - Example
- Access Token Request
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
- Successful Access Token Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"example",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
4 - Request
- URI:
- the end point location is typically provided in the service documentation.
- The endpoint URI MAY include anapplication/x-www-form-urlencoded formatted query component, which MUST be retained when adding additional query parameters.
- The endpoint URI MUST NOT include a fragment component.
- HTTPS: Since requests to the token endpoint result in the transmission of clear-text credentials (in the HTTP request and response), the authorization server MUST require the use of TLS when sending requests to the token endpoint.
- HTTP Method: The client MUST use the HTTP “POST” method when making access token requests.
- Parameters sent without a value MUST be treated as if they were omitted from the request.
- The authorization server MUST ignore unrecognized request parameters.
- Request and response parameters MUST NOT be included more than once.
4.1 - Client Id
- An authenticated client MAY use the client_id request parameter to identify itself when sending requests to the token endpoint.
- An unauthenticated client MUST send its “client_id” in the authorization_code grant_type request (to prevent itself from inadvertently accepting a code intended for a client with a different “client_id”. This protects the client from substitution of the authentication code. (It provides no additional security for the protected resource.)
4.2 - Scope request
See scope request
5 - Response
5.1 - Scope response
See scope response
6 - Flow
mermaid.initialize({
startOnLoad:true,
sequence:{
useMaxWidth:true,
boxTextMargin:5
}
});
<div class="mermaid">
sequenceDiagram
participant CL as Client
participant AS as Token Endpoint
CL->>AS: (A) Presents an authorization grant or a refresh token
AS->>CL: (B) Issues an access token and a refresh token.
</div>
- (A) The client requests an access token (and refresh token) by authenticating with the token endpoint (authorization server component) and presenting an authorization grant or a refresh token.
- (B) The token endpoint (authorization server component) authenticates the client and validates the authorization grant, and if valid, issues an access token and a refresh token.