Home

Auth

List token accessors

get

Returns a list of token accessor IDs which can then be used to discover their properties or revoke them. Requires both list and sudo capabilities on the auth/token/accessors path.

Query parameters
liststring · enumRequired

Must be set to "true"

Possible values:
Responses
200

A list of token accessor IDs.

application/json
get
GET /v1/auth/token/accessors HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "keys": [
    "ac7d50e0-a67f-4b56-a04d-69f2e06e6e2e",
    "31bb5c18-795b-482d-8bcb-889c1aa7a5f9"
  ]
}

Create a new orphan token

post

Creates an orphan token that is not tied to a parent token. Orphan tokens do not expire when the parent token expires and are not revoked when the parent is revoked.

Body
idstringOptional

Custom client token ID (root only). Cannot contain "." or start with "s.".

role_namestringOptional

Name of the token role.

policiesstring[]Optional

Policies to assign to the token.

no_parentbooleanOptional

If true, creates an orphan token. Requires root or sudo.

Default: false
no_default_policybooleanOptional

If true, excludes the default policy.

Default: false
renewablebooleanOptional

Whether the token can be renewed.

Default: true
leasestringOptionalDeprecated

Deprecated. Use ttl instead.

ttlstringOptional

TTL (e.g., "1h").

typestring · enumOptional

Token type.

Possible values:
explicit_max_ttlstringOptional

Explicit max TTL that cannot be exceeded.

display_namestringOptional

Display name for the token.

Default: token
num_usesintegerOptional

Max number of uses. 0 means unlimited.

Default: 0
periodstringOptional

Periodic renewal interval. Requires root or sudo.

entity_aliasstringOptional

Entity alias to associate with (must be allowed in role).

Responses
200

Token successfully created

application/json
post
POST /v1/auth/token/create-orphan HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "policies": [
    "web",
    "stage"
  ],
  "meta": {
    "user": "armon"
  },
  "ttl": "1h",
  "renewable": true
}
{
  "request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1",
  "lease_id": "",
  "renewable": true,
  "lease_duration": 3600,
  "data": null,
  "wrap_info": null,
  "warnings": [],
  "auth": {
    "client_token": "s.abcde12345fghij67890",
    "accessor": "B6oixijqmeR4bsLOJH88Ska9",
    "policies": [
      "default"
    ],
    "token_policies": [
      "default"
    ],
    "metadata": {
      "user": "example"
    },
    "lease_duration": 3600,
    "renewable": true,
    "entity_id": "",
    "token_type": "service",
    "orphan": true,
    "num_uses": 1
  }
}

Create token with role

post

Creates a new token using the configuration of the specified role. The role may override parameters passed in the request body.

Path parameters
role_namestringRequired

The name of the token role to use for token creation.

Body
display_namestringOptional

Name to associate with this token

entity_aliasstringOptional

Name of the entity alias to associate with this token

explicit_max_ttlstringOptional

Explicit Max TTL of this token

idstringOptional

Value for the token

leasestringOptionalDeprecated

Use 'ttl' instead

metaobject · kvpairsOptional

Arbitrary key=value metadata to associate with the token

no_default_policybooleanOptional

Do not include default policy for this token

no_parentbooleanOptional

Create the token with no parent

num_usesintegerOptional

Max number of uses for this token

periodstringOptional

Renew period

policiesstring[]Optional

List of policies for the token

renewablebooleanOptional

Allow token to be renewed past its initial TTL up to system/mount maximum TTL

Default: true
ttlstringOptional

Time to live for this token

typestringOptional

Token type

Responses
200

Token successfully created

application/json
post
POST /v1/auth/token/create/{role_name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "display_name": "text",
  "entity_alias": "text",
  "explicit_max_ttl": "text",
  "id": "text",
  "meta": {},
  "no_default_policy": true,
  "no_parent": true,
  "num_uses": 1,
  "period": "text",
  "policies": [
    "text"
  ],
  "renewable": true,
  "ttl": "text",
  "type": "text"
}
{
  "auth": {
    "client_token": "s.1234567890abcdef",
    "policies": [
      "default",
      "web",
      "dev"
    ],
    "lease_duration": 3600,
    "renewable": true,
    "token_type": "service",
    "orphan": false
  }
}

Lookup a token

post

Returns detailed information about the specified client token. This endpoint requires a token with sufficient capabilities to perform lookups.

Body
anyOptional
Responses
200

Token lookup successful

application/json
post
POST /v1/auth/token/lookup HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*

{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2764790
  }
}

Lookup a token (Accessor)

post

Returns detailed information about a token using its accessor. This endpoint requires a token with sufficient capabilities to perform lookups.

Body
anyOptional
Responses
200

Token lookup by accessor successful

application/json
Responseany
post
POST /v1/auth/token/lookup-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed"
}
{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2763902
  }
}

Lookup a token (Self)

get

Returns detailed information about the currently authenticated client token. This endpoint requires the caller to include a valid Vault token.

Responses
200

Token self-lookup successful

application/json
Responseany
get
GET /v1/auth/token/lookup-self HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "data": {
    "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed",
    "creation_time": 1523979354,
    "creation_ttl": 2764800,
    "display_name": "ldap2-tesla",
    "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9",
    "expire_time": "2018-05-19T11:35:54.466476215-04:00",
    "explicit_max_ttl": 0,
    "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed",
    "identity_policies": [
      "dev-group-policy"
    ],
    "issue_time": "2018-04-17T11:35:54.466476078-04:00",
    "meta": {
      "username": "tesla"
    },
    "num_uses": 0,
    "orphan": true,
    "path": "auth/ldap2/login/tesla",
    "policies": [
      "default",
      "testgroup2-policy"
    ],
    "renewable": true,
    "ttl": 2764790
  }
}

Renew a token (Accessor)

post

Renews a lease associated with a token using its accessor. This is used to prevent expiration and automatic revocation of the token. The token must be renewable and have an active lease.

Body
accessorstringOptional

Accessor of the token to renew (request body)

incrementinteger · secondsOptional

The desired increment in seconds to the token expiration

Default: 0
Responses
200

Token successfully renewed

application/json
Responseany
post
POST /v1/auth/token/renew-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "accessor": "7JFKXuXKXa2D44YfDiovZ9aq"
}
{
  "auth": {
    "client_token": "",
    "policies": [
      "web",
      "stage"
    ],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

Renew a token (Self)

post

Renews a lease associated with the calling token. This prevents the token from expiring and being automatically revoked. Renewal is only possible if the token is renewable and has an active lease.

Body
incrementinteger · secondsOptional

The desired increment in seconds to the token expiration

Default: 0
tokenstringOptional

Token to renew (unused, does not need to be set)

Responses
200

Token successfully renewed

application/json
Responseany
post
POST /v1/auth/token/renew-self HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "increment": "1h"
}
{
  "auth": {
    "client_token": "ABCD",
    "policies": [
      "web",
      "stage"
    ],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}

Revoke a token

post

Revokes the specified token and all child tokens derived from it. Any dynamic secrets associated with the token are also revoked.

Body
tokenstringRequired

Token to revoke

Responses
204

Token successfully revoked. No content returned.

post
POST /v1/auth/token/revoke HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "token": "ClientToken"
}
No content

Revoke a token accessor

post

Revokes the token associated with the specified accessor and all of its child tokens. This operation is useful in scenarios where the token ID is unavailable.

Body
accessorstringRequired

Accessor of the token to revoke

Responses
204

Token and its children successfully revoked. No content returned.

post
POST /v1/auth/token/revoke-accessor HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
No content

Revoke a token without revoking child tokens

post

Revokes the specified token and all secrets created with it, but does not revoke child tokens. The child tokens become orphaned and can be revoked later using /auth/token/revoke. This operation requires root-level privileges.

Body
tokenstringRequired

Token to revoke

Responses
204

Token successfully revoked. No content returned.

post
POST /v1/auth/token/revoke-orphan HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "token": "ClientToken"
}
No content

Revoke the calling token

post

Revokes the token used to authenticate this request, along with all child tokens. All secrets generated with the token are also revoked.

Body
objectOptional
Responses
204

Token successfully revoked. No content returned.

post
POST /v1/auth/token/revoke-self HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

List token roles

get

Lists the token roles configured in the token auth backend. Requires a token with list capability. This is equivalent to Vault's LIST method.

Responses
200

A list of token roles

application/json
get
GET /v1/auth/token/roles HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "data": {
    "keys": [
      "role1",
      "role2"
    ]
  }
}

Read a token role

get

Retrieves the configuration of the specified token role.

Path parameters
role_namestringRequired

Name of the token role

Responses
200

Token role data retrieved successfully

application/json
get
GET /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "data": {
    "allowed_policies": [
      "dev"
    ],
    "orphan": false,
    "renewable": true,
    "allowed_entity_aliases": [
      "web-entity-alias",
      "app-entity-*"
    ],
    "token_bound_cidrs": [
      "127.0.0.1/32",
      "128.252.0.0/16"
    ]
  }
}

Create or update a token role

post

Creates or replaces the specified token role configuration.

Path parameters
role_namestringRequired

Name of the token role

Body
allowed_entity_aliasesstring[]Optional

String or JSON list of allowed entity aliases. If set, specifies the entity aliases which are allowed to be used during token generation. This field supports globbing.

allowed_policiesstring[]Optional

If set, tokens can be created with any subset of the policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy names.

allowed_policies_globstring[]Optional

If set, tokens can be created with any subset of glob matched policies in this list, rather than the normal semantics of tokens being a subset of the calling token's policies. The parameter is a comma-delimited string of policy name globs.

bound_cidrsstring[]OptionalDeprecated

Use 'token_bound_cidrs' instead.

disallowed_policiesstring[]Optional

If set, successful token creation via this role will require that no policies in the given list are requested. The parameter is a comma-delimited string of policy names.

disallowed_policies_globstring[]Optional

If set, successful token creation via this role will require that no requested policies glob match any of policies in this list. The parameter is a comma-delimited string of policy name globs.

explicit_max_ttlinteger · secondsOptionalDeprecated

Use 'token_explicit_max_ttl' instead.

orphanbooleanOptional

If true, tokens created via this role will be orphan tokens (have no parent)

path_suffixstringOptional

If set, tokens created via this role will contain the given suffix as a part of their path. This can be used to assist use of the 'revoke-prefix' endpoint later on. The given suffix must match the regular expression.\w[\w-.]+\w

periodinteger · secondsOptionalDeprecated

Use 'token_period' instead.

renewablebooleanOptional

Tokens created via this role will be renewable or not according to this value. Defaults to "true".

Default: true
token_bound_cidrsstring[]Optional

Comma separated string or JSON list of CIDR blocks. If set, specifies the blocks of IP addresses which are allowed to use the generated token.

token_explicit_max_ttlinteger · secondsOptional

If set, tokens created via this role carry an explicit maximum TTL. During renewal, the current maximum TTL values of the role and the mount are not checked for changes, and any updates to these values will have no effect on the token being renewed.

token_no_default_policybooleanOptional

If true, the 'default' policy will not automatically be added to generated tokens

token_num_usesintegerOptional

The maximum number of times a token may be used, a value of zero means unlimited

token_periodinteger · secondsOptional

If set, tokens created via this role will have no max lifetime; instead, their renewal period will be fixed to this value. This takes an integer number of seconds, or a string duration (e.g. "24h").

token_typestringOptional

The type of token to generate, service or batch

Default: default-service
Responses
200

Token role created or updated successfully

application/json
post
POST /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Content-Type: application/json
Accept: */*
Content-Length: 175

{
  "allowed_policies": [
    "dev"
  ],
  "orphan": false,
  "renewable": true,
  "allowed_entity_aliases": [
    "web-entity-alias",
    "app-entity-*"
  ],
  "token_bound_cidrs": [
    "127.0.0.1/32",
    "128.252.0.0/16"
  ]
}
{
  "data": null,
  "warnings": null,
  "auth": null
}

Delete a token role

delete

Deletes the specified token role configuration.

Path parameters
role_namestringRequired

Name of the token role

Responses
204

Role deleted successfully. No content is returned.

delete
DELETE /v1/auth/token/roles/{role_name} HTTP/1.1
Host: localhost:8200
Accept: */*

No content

Tidy token store

post

Performs maintenance to clean up invalid entries in the token store. This operation reads all accessors, tokens, and secondary index entries to identify and remove invalid tokens, orphaned children, and unused cubbyholes. Use with caution due to potential memory and I/O load.

Responses
200

Tidy operation started successfully.

application/json
post
POST /v1/auth/token/tidy HTTP/1.1
Host: localhost:8200
Accept: */*

{
  "request_id": "84437c7f-36a1-6c1d-381d-14ec99217e94",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": [
    "Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs."
  ],
  "auth": null
}
PreviousAPINextDefault

Was this helpful?