Token Management APIs

POST /_xpack/security/oauth2/token

DELETE /_xpack/security/oauth2/token

The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. See Encrypting HTTP Client Communications. Alternatively, you can explicitly enable the xpack.security.authc.token.enabled setting. When you are running in production mode, a bootstrap check prevents you from enabling the token service unless you also enable TLS on the HTTP interface.

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.

A successful Get Token API 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.

The tokens returned by the Get Token API have a finite period of time for which they are valid and after that time period, they can no longer be used. That time period is defined by the xpack.security.authc.token.timeout setting. For more information, see Token service settings.

If you want to invalidate a token immediately, you can do so by using the Delete Token API.

The following parameters can be specified in the body of a POST request and pertain to creating a token:

The following parameters can be specified in the body of a DELETE request and pertain to deleting a token:

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

POST /_xpack/security/oauth2/token
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}

The following example output contains the access token, the amount of time (in seconds) that the token expires in, and the type:

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

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

To extend the life of an existing token, the token api may be called again with the refresh token within 24 hours of the token’s creation.

POST /_xpack/security/oauth2/token
{
    "grant_type": "refresh_token",
    "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}

The API will return a new token and refresh token. Each refresh token may only be used one time.

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

If a token must be invalidated immediately, you can do so by submitting a DELETE request to /_xpack/security/oauth2/token. For example, the following request invalidates an access token:

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

while the following request invalidates a refresh token

DELETE /_xpack/security/oauth2/token
{
  "refresh_token" : "vLBPvmAB6KvwvJZr27cS"
}

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

{
  "created" : true 
}