OpenSearch/x-pack/docs/en/rest-api/security/get-tokens.asciidoc

[role="xpack"]
[[security-api-get-token]]
=== Get token API
++++
<titleabbrev>Get token</titleabbrev>
++++

Creates a bearer token for access without requiring basic authentication.

[[security-api-get-token-request]]
==== {api-request-title}

`POST /_security/oauth2/token` 

[[security-api-get-token-prereqs]]
==== {api-prereq-title}

* To use this API, you must have the `manage_token` cluster privilege.

[[security-api-get-token-desc]]
==== {api-description-title}

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 
<<security-api-invalidate-token,invalidate token API>>.


[[security-api-get-token-request-body]]
==== {api-request-body-title}

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

`grant_type`::
(Required, string) The type of grant.
Supported grant types are: `password`, `_kerberos`,
`client_credentials` and `refresh_token`.

`client_credentials`:::
This grant type implements the Client Credentials Grant of OAuth2. It is geared
for machine to machine communication and is not suitable or designed for the
self-service user creation of tokens. It generates only access tokens that
cannot be refreshed. The premise is that the entity that uses
`client_credentials` has constant access to a set of (client, not end-user)
credentials and can authenticate itself at will. 

`_kerberos`::: 
This grant type is supported internally and implements SPNEGO based Kerberos
support. The `_kerberos` grant type may change from version to version.

`password`:::
This grant type implements the Resource Owner Password Credentials Grant of
OAuth2. In this grant, a trusted client exchanges the end user's credentials
for an access token and (possibly) a refresh token. The request needs to be made
by an authenticated user but happens _on behalf_ of another authenticated user
(the one whose credentials are passed as request parameters). This grant type is
not suitable or designed for the self-service user creation of tokens.

`refresh_token`:::
This grant type implements the Refresh Token Grant of OAuth2.
In this grant a user exchanges a previously issued refresh token for a new access token and a new refresh token.

`password`::
(Optional^*^, string) The user's password. If you specify the `password` grant type, this
parameter is required. This parameter is not valid with any other supported
grant type.

`kerberos_ticket`::
(Optional^*^, string) The base64 encoded kerberos ticket. If you specify the
`_kerberos` grant type, this parameter is required. This parameter is not valid
with any other supported grant type.

`refresh_token`::
(Optional^*^, string) The string that was returned when you created the token, 
which enables you to extend its life. If you specify the `refresh_token` grant
type, this parameter is required. This parameter is not valid with any other
supported grant type.

`scope`::
(Optional, 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`::
(Optional^*^, string) The username that identifies the user. If you specify the `password` 
grant type, this parameter is required. This parameter is not valid with any
other supported grant type.

[[security-api-get-token-example]]
==== {api-examples-title}

The following example obtains a token using the `client_credentials` grant type,
which simply creates a token as the authenticated user:

[source,console]
--------------------------------------------------
POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}
--------------------------------------------------

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

[source,console-result]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200
}
--------------------------------------------------
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_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
--------------------------------------------------
// NOTCONSOLE

The following example obtains a token for the `test_admin` user using the
`password` grant type:

[source,console]
--------------------------------------------------
POST /_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, the type, and the refresh token:

[source,console-result]
--------------------------------------------------
{
  "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-refresh-token]]
To extend the life of an existing token obtained using the `password` grant type,
you can call the API again with the refresh token within 24 hours of the token's
creation. For example:

[source,console]
--------------------------------------------------
POST /_security/oauth2/token
{
  "grant_type": "refresh_token",
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// 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,console-result]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
}
--------------------------------------------------
// TESTRESPONSE[s/dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==/$body.access_token/]
// TESTRESPONSE[s/vLBPvmAB6KvwvJZr27cS/$body.refresh_token/]

The following example obtains a access token and refresh token using the `kerberos` grant type,
which simply creates a token in exchange for the base64 encoded kerberos ticket:

[source,js]
--------------------------------------------------
POST /_security/oauth2/token
{
  "grant_type" : "_kerberos",
  "kerberos_ticket" : "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAgEFoQMCAQ6iBtaDcp4cdMODwOsIvmvdX//sye8NDJZ8Gstabor3MOGryBWyaJ1VxI4WBVZaSn1WnzE06Xy2"
}
--------------------------------------------------
// NOTCONSOLE

The API will return a new token and refresh token if kerberos authentication is successful.
Each refresh token may only be used one time. When the mutual authentication is requested in the Spnego GSS context,
 a base64 encoded token will be returned by the server in the `kerberos_authentication_response_token`
 for clients to consume and finalize the authentication.

[source,js]
--------------------------------------------------
{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "refresh_token": "vLBPvmAB6KvwvJZr27cS"
  "kerberos_authentication_response_token": "YIIB6wYJKoZIhvcSAQICAQBuggHaMIIB1qADAg"
}
--------------------------------------------------
// NOTCONSOLE