Get a token Generally available; Added in 5.5.0

POST /_security/oauth2/token
Api key auth Basic auth Bearer auth

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
External documentation
application/json

Body Required

  • grant_type string

    Values are password, client_credentials, _kerberos, or 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
  • 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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • access_token string Required
    • expires_in number Required
    • scope string
    • type string Required
    • refresh_token string
    • kerberos_authentication_response_token string
    • authentication object Additional properties
      Hide authentication attributes Show authentication attributes object

      • email string | null

        One of:
        string-1 string string-2 string | null

      • full_name string | null

        One of:
        Name string string-2 string | null
      • metadata object Required
        Hide metadata attribute Show metadata attribute object
        • * object Additional properties
      • roles array[string] Required
      • username string Required
      • enabled boolean Required
      • profile_uid string
      • authentication_realm object Required
        Hide authentication_realm attributes Show authentication_realm attributes object
        • name string Required
        • type string Required
      • lookup_realm object Required
        Hide lookup_realm attributes Show lookup_realm attributes object
        • name string Required
        • type string Required
      • authentication_provider object
        Hide authentication_provider attributes Show authentication_provider attributes object
        • type string Required
        • name string Required
      • authentication_type string Required
POST /_security/oauth2/token 
POST /_security/oauth2/token
{
  "grant_type" : "client_credentials"
}
resp = client.security.get_token(
    grant_type="client_credentials",
)
const response = await client.security.getToken({
  grant_type: "client_credentials",
});
response = client.security.get_token(
  body: {
    "grant_type": "client_credentials"
  }
)
$resp = $client->security()->getToken([
    "body" => [
        "grant_type" => "client_credentials",
    ],
]);
curl -X POST -H "Authorization: ApiKey $ELASTIC_API_KEY" -H "Content-Type: application/json" -d '{"grant_type":"client_credentials"}' "$ELASTICSEARCH_URL/_security/oauth2/token"
client.security().getToken(g -> g
    .grantType(AccessTokenGrantType.ClientCredentials)
);
Request 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. 
{
  "grant_type" : "client_credentials"
}
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. 
{
  "grant_type" : "password",
  "username" : "test_admin",
  "password" : "x-pack-test-password"
}
Response examples (200)
A successful response from `POST /_security/oauth2/token`. 
{
  "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"
  }
}
A successful response from `POST /_security/oauth2/token`. 
{
  "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"
  }
}