vault/website/content/api-docs/auth/token.mdx

---
layout: api
page_title: Token - Auth Methods - HTTP API
description: This is the API documentation for the Vault token auth method.
---

# Token auth method (API)

This is the API documentation for the Vault token auth method. For
general information about the usage and operation of the token method, please
see the [Vault Token method documentation](/vault/docs/auth/token).

## List accessors

This endpoint lists token accessor. This requires `sudo` capability, and access
to it should be tightly controlled as the accessors can be used to revoke very
large numbers of tokens and their associated leases at once.

| Method | Path                    |
| :----- | :---------------------- |
| `LIST` | `/auth/token/accessors` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/token/accessors
```

### Sample response

```json
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "476ea048-ded5-4d07-eeea-938c6b4e43ec",
      "bb00c093-b7d3-b0e9-69cc-c4d85081165b"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

## Create token

Creates a new token. Certain options are only available when called by a
root token. If used via the `/auth/token/create-orphan` endpoint, a root
token is not required to create an orphan token (otherwise set with the
`no_parent` option). If used with a role name in the path, the token will
be created against the specified role name; this may override options set
during this call.

| Method | Path                            |
| :----- | :------------------------------ |
| `POST` | `/auth/token/create`            |
| `POST` | `/auth/token/create-orphan`     |
| `POST` | `/auth/token/create/:role_name` |

### Parameters

- `id` `(string: "")` – The ID of the client token. Can only be specified by a
  root token. The ID provided may not contain a `.` character. Otherwise, the
  token ID is a randomly generated value.

  _Note:_ The ID should not start with the `s.` prefix.

- `role_name` `(string: "")` – The name of the token role.
- `policies` `(array: "")` – A list of policies for the token. This must be a
  subset of the policies belonging to the token making the request, unless
  the calling token is root or contains `sudo` capabilities to `auth/token/create`.
  If not specified, defaults to all the policies of the calling token.
- `meta` `(map: {})` – A map of string to string valued metadata. This is
  passed through to the audit devices.
- `no_parent` `(bool: false)` - This argument only has effect if used by a root
  or sudo caller. When set to true, the token created will not have a parent.
- `no_default_policy` `(bool: false)` - If true the `default` policy will not be
  contained in this token's policy set.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
  to be renewed past its initial TTL. Setting the value to `true` will allow
  the token to be renewable up to the system/mount maximum TTL.
- `lease` `(string: "")` - DEPRECATED; use `ttl` instead
- `ttl` `(string: "")` - The TTL period of the token, provided as "1h", where
  hour is the largest suffix. If not provided, the token is valid for the
  [default lease TTL](/vault/docs/configuration), or indefinitely if the
  root policy is used.
- `type` `(string: "")` - The token type. Can be "batch" or "service". Defaults
  to the type specified by the role configuration named by `role_name`.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
  max TTL set upon it. This maximum token TTL _cannot_ be changed later, and
  unlike with normal tokens, updates to the system/mount max TTL value will
  have no effect at renewal time -- the token will never be able to be renewed
  or used past the value set at issue time.
- `display_name` `(string: "token")` - The display name of the token.
- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be
  used to create a one-time-token or limited use token. The value of 0 has no
  limit to the number of uses.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
  no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
  will use the given period. Requires a root token or one with the sudo capability.
- `entity_alias` `(string: "")` - Name of the entity alias to associate with
  during token creation. Only works in combination with `role_name` argument
  and used entity alias must be listed in `allowed_entity_aliases`. If this has
  been specified, the entity will not be inherited from the parent.

### Sample payload

```json
{
  "policies": ["web", "stage"],
  "meta": {
    "user": "armon"
  },
  "ttl": "1h",
  "renewable": true
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/create
```

### Sample response

```json
{
  "request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": null,
  "wrap_info": null,
  "warnings": [
    "Policy \"stage\" does not exist",
    "Policy \"web\" does not exist"
  ],
  "auth": {
    "client_token": "s.wOrq9dO9kzOcuvB06CMviJhZ",
    "accessor": "B6oixijqmeR4bsLOJH88Ska9",
    "policies": ["default", "stage", "web"],
    "token_policies": ["default", "stage", "web"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true,
    "entity_id": "",
    "token_type": "service",
    "orphan": false,
    "num_uses": 0
  }
}
```

## Lookup a token

Returns information about the client token.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/auth/token/lookup` |

### Parameters

- `token` `(string: <required>)` - Token to lookup.

### Sample payload

```json
{
  "token": "ClientToken"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/lookup
```

### Sample response

```json
{
  "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 (Self)

Returns information about the current client token.

| Method | Path                      |
| :----- | :------------------------ |
| `GET`  | `/auth/token/lookup-self` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/token/lookup-self
```

### Sample response

```json
{
  "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)

Returns information about the client token from the accessor.

| Method | Path                          |
| :----- | :---------------------------- |
| `POST` | `/auth/token/lookup-accessor` |

### Parameters

- `accessor` `(string: <required>)` - Token accessor to lookup.

### Sample payload

```json
{
  "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/lookup-accessor
```

### Sample response

```json
{
  "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
  }
}
```

## Renew a token

Renews a lease associated with a token. This is used to prevent the expiration
of a token, and the automatic revocation of it. Token renewal is possible only
if there is a lease associated with it.

| Method | Path                |
| :----- | :------------------ |
| `POST` | `/auth/token/renew` |

### Parameters

- `token` `(string: <required>)` - Token to renew. This can be part of the URL
  or the body.
- `increment` `(string: "")` - An optional requested increment duration can be
  provided. This increment may not be honored, for instance in the case of periodic tokens.
  If not supplied, Vault will use the default TTL. This is specified as a numeric string
  with suffix like "30s" or "5m".

### Sample payload

```json
{
  "token": "ClientToken"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew
```

### Sample response

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

## Renew a token (Self)

Renews a lease associated with the calling token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token renewal is
possible only if there is a lease associated with it.

| Method | Path                     |
| :----- | :----------------------- |
| `POST` | `/auth/token/renew-self` |

### Parameters

- `increment` `(string: "")` - An optional requested increment duration can be
  provided. This increment may not be honored, for instance in the case of periodic tokens.
  If not supplied, Vault will use the default TTL. This is specified as a numeric string
  with suffix like "30s" or "5m".

### Sample payload

```json
{
  "increment": "1h"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew-self
```

### Sample response

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

## Renew a token (Accessor)

Renews a lease associated with a token using its accessor. This is used to
prevent the expiration of a token, and the automatic revocation of it. Token
renewal is possible only if there is a lease associated with it.

| Method | Path                         |
| :----- | :--------------------------- |
| `POST` | `/auth/token/renew-accessor` |

### Parameters

- `accessor` `(string: <required>)` - Accessor associated with the token to
  renew.
- `increment` `(string: "")` - An optional requested lease increment can be
  provided. This increment may be ignored.

### Sample payload

```json
{
  "accessor": "7JFKXuXKXa2D44YfDiovZ9aq"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/renew-accessor
```

### Sample response

```json
{
  "auth": {
    "client_token": "",
    "policies": ["web", "stage"],
    "metadata": {
      "user": "armon"
    },
    "lease_duration": 3600,
    "renewable": true
  }
}
```

## Revoke a token

Revokes a token and all child tokens. When the token is revoked, all dynamic secrets
generated with it are also revoked.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/auth/token/revoke` |

### Parameters

- `token` `(string: <required>)` - Token to revoke.

### Sample payload

```json
{
  "token": "ClientToken"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke
```

## Revoke a token (Self)

Revokes the token used to call it and all child tokens. When the token is
revoked, all dynamic secrets generated with it are also revoked.

| Method | Path                      |
| :----- | :------------------------ |
| `POST` | `/auth/token/revoke-self` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/auth/token/revoke-self
```

## Revoke a token accessor

Revoke the token associated with the accessor and all the child tokens. This is
meant for purposes where there is no access to token ID but there is need to
revoke a token and its children.

| Method | Path                          |
| :----- | :---------------------------- |
| `POST` | `/auth/token/revoke-accessor` |

### Parameters

- `accessor` `(string: <required>)` - Accessor of the token.

### Sample payload

```json
{
  "accessor": "2c84f488-2133-4ced-87b0-570f93a76830"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke-accessor
```

## Revoke token and orphan children

Revokes a token but not its child tokens. When the token is revoked, all secrets
generated with it are also revoked. All child tokens are orphaned, but can be
revoked sub-sequently using `/auth/token/revoke/`. This is a root-protected
endpoint.

| Method | Path                        |
| :----- | :-------------------------- |
| `POST` | `/auth/token/revoke-orphan` |

### Parameters

- `token` `(string: <required>)` - Token to revoke. This can be part of the URL
  or the body.

### Sample payload

```json
{
  "token": "ClientToken"
}
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/token/revoke-orphan
```

## Read token role

Fetches the named role configuration.

| Method | Path                           |
| :----- | :----------------------------- |
| `GET`  | `/auth/token/roles/:role_name` |

### Parameters

- `role_name` `(string: <required>)` - The name of the token role.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/token/roles/nomad
```

### Sample response

```javascript
{
  "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "allowed_entity_aliases": [
      "my-entity-alias"
    ],
    "allowed_policies": [],
    "disallowed_policies": [],
    "allowed_policies_glob": [],
    "disallowed_policies_glob": [],
    "explicit_max_ttl": 0,
    "name": "nomad",
    "orphan": false,
    "path_suffix": "",
    "period": 0,
    "renewable": true,
    "token_explicit_max_ttl": 0,
    "token_no_default_policy": false,
    "token_period": 0,
    "token_type": "default-service"
  },
  "warnings": null
}
```

## List token roles

List available token roles.

| Method | Path                |
| :----- | :------------------ |
| `LIST` | `/auth/token/roles` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST
    http://127.0.0.1:8200/v1/auth/token/roles
```

### Sample response

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

## Create/Update token role

Creates (or replaces) the named role. Roles enforce specific behavior when
creating tokens that allow token functionality that is otherwise not
available or would require `sudo`/root privileges to access. Role
parameters, when set, override any provided options to the `create`
endpoints. The role name is also included in the token path, allowing all
tokens created against a role to be revoked using the
`/sys/leases/revoke-prefix` endpoint.

| Method | Path                           |
| :----- | :----------------------------- |
| `POST` | `/auth/token/roles/:role_name` |

### Parameters

- `role_name` `(string: <required>)` – The name of the token role.
- `allowed_policies` `(list: [])` – 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. If at creation time
  `no_default_policy` is not set and `"default"` is not contained in
  `disallowed_policies` or glob matched in `disallowed_policies_glob`,
  the `"default"` policy will be added to the created token automatically.
- `disallowed_policies` `(list: [])` – 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. Adding `"default"` to
  this list will prevent `"default"` from being added automatically to created
  tokens.
- `allowed_policies_glob` `(list: [])` – 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. If at creation time
  `no_default_policy` is not set and `"default"` is not contained in
  `disallowed_policies` or glob matched in `disallowed_policies_glob`,
  the `"default"` policy will be added to the created token automatically.
  If combined with `allowed_policies` policies need to only match one of the two
  lists to be permitted. Note that unlike `allowed_policies` the policies listed
  in `allowed_policies_glob` will not be added to the token when no policies are
  specified in the call to `/auth/token/create/:role_name`.
- `disallowed_policies_glob` `(list: [])` – 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.
  Adding any glob that matches `"default"` to this list will prevent `"default"`
  from being added automatically to created tokens.
  If combined with `disallowed_policies` policies need to only match one of the
  two lists to be blocked.
- `orphan` `(bool: false)` - If `true`, tokens created against this policy will
  be orphan tokens (they will have no parent). As such, they will not be
  automatically revoked by the revocation of any other token.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
  to be renewed past its initial TTL. Setting the value to `true` will allow
  the token to be renewable up to the system/mount maximum TTL.
- `path_suffix` `(string: "")` - If set, tokens created against this role will
  have the given suffix as part of their path in addition to the role name. This
  can be useful in certain scenarios, such as keeping the same role name in the
  future but revoking all tokens created against it before some point in time.
  The suffix can be changed, allowing new callers to have the new suffix as part
  of their path, and then tokens with the old suffix can be revoked via
  `/sys/leases/revoke-prefix`.
- `allowed_entity_aliases` `(string: "", or list: [])` - 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.
  Note that `allowed_entity_aliases` is not case sensitive.

@include 'tokenstorefields.mdx'

### Sample payload

```json
  "allowed_policies": [
    "dev"
  ],
  "name": "nomad",
  "orphan": false,
  "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"],
  "renewable": true,
  "allowed_entity_aliases": ["web-entity-alias", "app-entity-*"]
```

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST
    --data @payload.json
    http://127.0.0.1:8200/v1/auth/token/roles/nomad
```

## Delete token role

This endpoint deletes the named token role.

| Method   | Path                           |
| :------- | :----------------------------- |
| `DELETE` | `/auth/token/roles/:role_name` |

### Parameters

- `role_name` `(string: <required>)` - The name of the token role.

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/auth/token/roles/admins
```

## Tidy tokens

Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. On Enterprise, Tidy will only impact the tokens in the
specified namespace, or the root namespace if unspecified.

Generally, running this is not needed unless upgrade notes or support personnel
suggest it. There are two potential dangers to running tidy: first, this will
perform a lot of read I/O to the storage method, as it will essentially reload the
entirety of the token store into memory. Depending on how much cleanup is
required (usually very little) there may also be a large number of writes.
Second, this will cause Vault's memory usage to balloon up, because the default
Vault internal cache is unlimited in size and every value read from storage will
be cached. Listing the `/auth/token/accessors` endpoint is a good way to get
some sense of the potential impact: tidy does this and more, so if this call creates problems
for your cluster, it would be wise to give Vault more resources before attempting
tidy. Note that the request may time out depending on
[max duration](/vault/docs/configuration#default_max_request_duration)
and your client's timeout configuration, make sure to allow it run to completion
to properly judge the impact.

Tidy will load every token accessor and cubbyhole in the namespace, as well
as all the secondary index entries that are used to group tokens into trees so
that parent token revocation also revokes child tokens.

For each parent token listed in the secondary index, tidy will check if the token
still exists in storage, and if not its child tokens that still exist will be
made orphans, then the parent token will be removed from the secondary index.

For each accessor found, tidy will check if the corresponding token still exists
in storage, and if not will delete the accessor. If the token still exists in
storage but shouldn't, tidy will try to revoke it and any child leases it might
have, then delete the accessor.

Finally, any cubbyhole entries that are associated with tokens which weren't deemed
valid in the above steps will be deleted.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/auth/token/tidy` |

### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/auth/token/tidy
```

### Sample response

```json
{
  "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
}
```