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.

Authorizations

VaultToken

Query parameters

liststring · enumRequired

Must be set to "true"

Possible values:

Responses

200

A list of token accessor IDs.

application/json

403

Forbidden – caller lacks required capabilities (list and sudo).

application/json

400'

Bad Request – likely due to missing or incorrect query parameters.

application/json

get

/auth/token/accessors

HTTPcURLJavaScriptPython

GET /v1/auth/token/accessors?list=true 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.

Authorizations

VaultToken

Body

application/json

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

400

Bad Request – Invalid or missing input fields

application/json

403

Forbidden – The caller lacks permission to create orphan tokens

application/json

post

/auth/token/create-orphan

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Path parameters

role_namestringRequired

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

Body

application/json

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

400

Bad Request – Invalid input or missing required fields

application/json

403

Forbidden – Insufficient privileges to create token with specified parameters

application/json

post

/auth/token/create/{role_name}

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

anyOptional

Responses

200

Token lookup successful

application/json

400

Bad Request – Missing or malformed token field

application/json

403

Forbidden – Insufficient permissions to look up this token

application/json

post

/auth/token/lookup

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

anyOptional

Responses

200

Token lookup by accessor successful

application/json

Responseany

400

Bad Request – Missing or malformed accessor field

application/json

403

Forbidden – Insufficient permissions to perform accessor lookup

application/json

post

/auth/token/lookup-accessor

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Responses

200

Token self-lookup successful

application/json

Responseany

403

Forbidden – The client token is invalid or lacks access

application/json

get

/auth/token/lookup-self

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

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

400

Bad Request – Missing or invalid accessor or token not renewable

application/json

403

Forbidden – Caller lacks permission to renew the token

application/json

post

/auth/token/renew-accessor

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

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

403

Forbidden – Token is not renewable or not authorized

application/json

post

/auth/token/renew-self

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

tokenstringRequired

Token to revoke

Responses

204

Token successfully revoked. No content returned.

400

Invalid input or missing token.

application/json

403

Forbidden – the client token does not have permission to revoke the specified token.

application/json

post

/auth/token/revoke

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

accessorstringRequired

Accessor of the token to revoke

Responses

204

Token and its children successfully revoked. No content returned.

400

Invalid accessor or input data.

application/json

403

Forbidden – the client token does not have permission to revoke the specified accessor.

application/json

post

/auth/token/revoke-accessor

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

tokenstringRequired

Token to revoke

Responses

204

Token successfully revoked. No content returned.

400

Invalid token or malformed input.

application/json

403

Forbidden – the client token does not have permission to revoke this token.

application/json

post

/auth/token/revoke-orphan

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Body

application/json

objectOptional

Responses

204

Token successfully revoked. No content returned.

400

Invalid request or the token cannot be revoked.

application/json

403

Forbidden – the token does not have permission to revoke itself.

application/json

post

/auth/token/revoke-self

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Responses

200

A list of token roles

application/json

400

Bad request – malformed token or missing authentication

application/json

403

Forbidden – token does not have permission to list roles

application/json

get

/auth/token/roles

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Path parameters

role_namestringRequired

Name of the token role

Responses

200

Token role data retrieved successfully

application/json

404

Role not found

application/json

get

/auth/token/roles/{role_name}

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Path parameters

role_namestringRequired

Name of the token role

Body

application/json

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

400

Invalid role configuration

application/json

403

Permission denied

application/json

post

/auth/token/roles/{role_name}

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Path parameters

role_namestringRequired

Name of the token role

Responses

204

Role deleted successfully. No content is returned.

403

Permission denied

application/json

404

Role not found

application/json

delete

/auth/token/roles/{role_name}

HTTPcURLJavaScriptPython

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.

Authorizations

VaultToken

Responses

200

Tidy operation started successfully.

application/json

403

Permission denied to perform tidy operation.

application/json

500

Internal server error while attempting to start tidy.

application/json

post

/auth/token/tidy

HTTPcURLJavaScriptPython

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
}