Service: OAuth2 Token Request with Refresh Token Grant

Refresh token is a token that can be used to request a new access token, e.g when an access token is expired, without the need for user re-authorization. A refresh token is issued together with an access token. For security reasons, refresh tokens are only issued for confidential clients.

When a client sends an OAuth2 token request with refresh token grant, Kustvakt will revoke the given refresh token and the access token associated with it. Kustvakt will then issue a new access token and a new refresh token.

This service requires client authentication for confidential clients. Client credentials should be included either in Authorization header or in the request body.

Available in: full version

Method: POST

Service URL: root/oauth2/token

Parameters

Header Parameters

Name	Required	Description	Value
Authorization	yes, for confidential clients	Client authentication with HTTP Basic Authentication mechanism. Alternatively without Authorization header, client credentials can be specified in the request body. Client authentication is required for confidential clients.	client_id:client_secret encoded in Base64
Content-Type	yes	content type of the input data	application/x-www-form-urlencoded

Request body

URL-encoded form parameters

Name	Required	Description	Type	Values
grant_type	yes	The OAuth2 grant type.	String	refresh_token
client_id	yes	The client identifier.	String	client_id given on client registration
client_secret	yes, for confidential clients	The client secret. Specify either in the Authorization header or the request body. Client authentication is required for confidential clients.	String	client_secret given on client registration
refresh_token	yes	The refresh token string.	String
scope	no	The requested authorization scopes separated by space. Default: the scopes of the access token issued together with the given refresh token. The requested scopes can be less than, but not different from the default scopes (i.e. new scopes cannot be requested).	String	search match_info

Examples

Example Client

Credentials	Value
Client id	dRJnpFH6RHTr6L7bNhrn7F
Client secret	_IGaQqvUUrPTzRKJvqPYnA

Authorization header

• Scheme : Basic

• Value: Base64 encoding for client_id:client_secret

  ZFJKbnBGSDZSSFRyNkw3Yk5ocm43RjpfSUdhUXF2VVVyUFR6UktKdnFQWW5B

Existing or expired access token

{
    "access_token": "4dcf8784ccfd26fac9bdb82778fe60e2",
    "refresh_token" : "hlWci75xb8atDiq3924NUSvOdtAh7Nlf9z",
    "scope": "search match_info",
    "token_type": "Bearer",
    "expires_in": 259200
}

Refresh token grant with client authentication via Authorization header

• Scope parameter is not specified.

curl -H 'Content-Type: application/x-www-form-urlencoded' 
     -H 'Authorization: Basic ZFJKbnBGSDZSSFRyNkw3Yk5ocm43RjpfSUdhUXF2VVVyUFR6UktKdnFQWW5B'
     -d 'grant_type=refresh_token
         &client_id=dRJnpFH6RHTr6L7bNhrn7F
         &refresh_token=hlWci75xb8atDiq3924NUSvOdtAh7Nlf9z' 
     http://localhost:8089/api/oauth2/token

Refresh token grant with client credentials in the request body

• Scope is less than the expired access token.

curl -H 'Content-Type: application/x-www-form-urlencoded' 
     -d 'grant_type=refresh_token
         &client_id=dRJnpFH6RHTr6L7bNhrn7F
         &client_secret=_IGaQqvUUrPTzRKJvqPYnA
         &refresh_token=hlWci75xb8atDiq3924NUSvOdtAh7Nlf9z
         &scope=search' 
     http://localhost:8089/api/oauth2/token

Response

• New access token and refresh token

{
    "access_token": "Dt7HsFf_ECIDdPJow4XiwwQzCiLEn5K_qeBPFZOdbAuQ",
    "refresh_token" : "86FN7ta2MY1bHWf2uU8GUAUap0yF-Yq8r6h4id-H8rzQ",
    "scope": "search",
    "token_type": "Bearer",
    "expires_in": 259200
}