Get a token

POST /_security/oauth2/token

Create a bearer token for access without requiring basic authentication. The tokens are created by the Elasticsearch Token Service, which is automatically enabled when you configure TLS on the HTTP interface. 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. If you want to invalidate a token immediately, you can do so by using the invalidate token API.

Required authorization

Cluster privileges: manage_token

Read the reference documentation

Request

grant_type enum AccessTokenGrantType

The type of grant. Supported grant types are: password, _kerberos, client_credentials, and refresh_token.

Supported values include:

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

Values: password client_credentials _kerberos refresh_token

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.

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

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

Response

application/json

Examples

Run POST /_security/oauth2/token to obtain a token using the client_credentials grant type, which simply creates a token as the authenticated user.

Request Console 1 / 8 languages

Console Kibana Dev Tools

POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}

JavaScript Elasticsearch JavaScript Client

const response = await client.security.getToken({
  grant_type: "client_credentials",
});

Python Elasticsearch Python Client

resp = client.security.get_token(
    grant_type="client_credentials",
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/oauth2/token" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials"
  }'

Java Elasticsearch Java Client

client.security().getToken(g -> g
    .grantType(AccessTokenGrantType.ClientCredentials)
);

C# Elasticsearch .NET Client

var response = await client.Security
    .GetTokenAsync(d1 => d1
        .GrantType(AccessTokenGrantType.ClientCredentials)
    );

PHP Elasticsearch PHP Client

$resp = $client->security()->getToken([
    "body" => [
        "grant_type" => "client_credentials",
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.security.get_token(
  body: {
    "grant_type": "client_credentials"
  }
)

Response

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "realm"
  }
}

Run POST /_security/oauth2/token to obtain a token for the test_admin user using the password grant type. This request needs to be made by an authenticated user with sufficient privileges that may or may not be the same as the one whose username is passed in the username parameter.

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_security/oauth2/token" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}'

Response

{
  "access_token" : "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==",
  "type" : "Bearer",
  "expires_in" : 1200,
  "authentication" : {
    "username" : "test_admin",
    "roles" : [
      "superuser"
    ],
    "full_name" : null,
    "email" : null,
    "metadata" : { },
    "enabled" : true,
    "authentication_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "lookup_realm" : {
      "name" : "file",
      "type" : "file"
    },
    "authentication_type" : "realm"
  }
}

Required authorization

Request { grant_type , scope , password , kerberos_ticket , refresh_token , username , }

Response

Request