Token Management APIs

The token API enables you to create and invalidate bearer tokens for access without requiring basic authentication. The get token API takes the same parameters as a typical OAuth 2.0 token API except for the use of a JSON request body.

To obtain a token, submit a POST request to the /_xpack/security/oauth2/token endpoint.

POST /_xpack/security/oauth2/token
{
  "grant_type" : "password",
  "username" : "elastic",
  "password" : "changeme"
}

Table 36. Token Request Fields

Name

Required

Description

username

yes

The username that identifies the user.

password

yes

The user’s password.

grant_type

yes

The type of grant. Currently only the password grant type is supported.

scope

no

The scope of the token. Currently tokens are only issued for a scope of FULL regardless of the value sent with the request.


A successful call returns a JSON structure that contains the access token, the amount of time (seconds) that the token expires in, the type, and the scope if available.

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200
}

A successful call returns a JSON structure that shows whether the user has been created or updated.

The token returned by this API can be used by sending a request with a Authorization header with a value having the prefix Bearer ` followed by the value of the `access_token.

curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health

The tokens returned from this API have a finite period of time for which they are valid and after that time period, they can no longer be used. However, if a token must be invalidated immediately, you can do so by submitting a DELETE request to /_xpack/security/oauth2/token.

DELETE /_xpack/security/oauth2/token
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}

A successful call returns a JSON structure that indicates whether the token has already been invalidated.

{
  "created" : true 
}

When a token has already been invalidated, created is set to false.