[role="xpack"]
[[security-api-tokens]]
=== Token Management APIs

The `token` API enables you to create and invalidate bearer tokens for access
without requiring basic authentication.

==== Request

`POST /_xpack/security/oauth2/token` +

`DELETE /_xpack/security/oauth2/token`

==== Description

The tokens are created by the {es} Token Service, which is automatically enabled
when you configure TLS on the HTTP interface. See <<tls-http>>. 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.


==== Request Body

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

`grant_type`::
(string) The type of grant. Currently only the `password` grant type is supported.

`password` (required)::
(string) The user's password.

`scope`::
(string) The scope of the token. Currently tokens are only issued for a scope of
`FULL` regardless of the value sent with the request.

`username` (required)::
(string) The username that identifies the user.

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

`token`::
(string) An access token.

==== Examples
[[security-api-get-token]]
To obtain a token, submit a POST request to the `/_xpack/security/oauth2/token`
endpoint.

[source,js]
--------------------------------------------------
POST /_xpack/security/oauth2/token
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}
--------------------------------------------------
// CONSOLE

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

[source,js]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]

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`.

[source,shell]
--------------------------------------------------
curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
--------------------------------------------------

[[security-api-refresh-token]]
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.

[source,js]
--------------------------------------------------
POST /_xpack/security/oauth2/token
{
    "grant_type": "refresh_token",
    "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// CONSOLE
// TEST[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]
// TEST[continued]

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

[source,js]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]

[[security-api-invalidate-token]]
If a token must be invalidated immediately, you can do so by submitting a DELETE
request to `/_xpack/security/oauth2/token`.  For example:

[source,js]
--------------------------------------------------
DELETE /_xpack/security/oauth2/token
{
  "token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ=="
}
--------------------------------------------------
// CONSOLE
// TEST[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
// TEST[continued]

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

[source,js]
--------------------------------------------------
{
  "created" : true <1>
}
--------------------------------------------------
// TESTRESPONSE

<1> When a token has already been invalidated, `created` is set to false.