open-vault/website/source/docs/auth/token.html.md

layout	page_title	sidebar_current	description
docs	Auth Backend: Token	docs-auth-token	The token store auth backend is used to authenticate using tokens.

Auth Backend: Token

The token backend is the only auth backend that is built-in and automatically available at /auth/token as well as with first-class built-in CLI methods such as vault token-create. It allows users to authenticate using a token, as well to create new tokens, revoke secrets by token, and more.

When any other auth backend returns an identity, Vault core invokes the token backend to create a new unique token for that identity.

The token store can also be used to bypass any other auth backend: you can create tokens directly, as well as perform a variety of other operations on tokens such as renewal and revocation.

Please see the token concepts page dedicated to tokens.

Authentication

Via the CLI

$ vault auth <token>
...

Via the API

The token is set directly as a header for the HTTP API. The name of the header should be "X-Vault-Token" and the value should be the token.

API

/auth/token/accessors

LIST or GET

Description

Lists token accessors. 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

LIST or GET

URL

`/auth/token/accessors` (LIST)

`/auth/token/accessors?list=true` (GET)

Parameters

None

Returns

```javascript
{
  "data": {
    "keys": ["476ea048-ded5-4d07-eeea-938c6b4e43ec", "bb00c093-b7d3-b0e9-69cc-c4d85081165b"]
  }
}
```

/auth/token/create

/auth/token/create-orphan

/auth/token/create/[role_name]

POST

Description

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

POST

URLs

`/auth/token/create`

`/auth/token/create-orphan`

`/auth/token/create/`

Parameters

• id optional The ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated UUID.
• policies optional A list of policies for the token. This must be a subset of the policies belonging to the token making the request, unless root. If not specified, defaults to all the policies of the calling token.
• meta optional A map of string to string valued metadata. This is passed through to the audit backends.
• no_parent optional If true and set by a root caller, the token will not have the parent token of the caller. This creates a token with no parent.
• no_default_policy optional If true the `default` policy will not be a part of this token's policy set.
• renewable optional Set to `false` to disable the ability of the token to be renewed past its initial TTL. Specifying `true`, or omitting this option, will allow the token to be renewable up to the system/mount maximum TTL.
• lease optional DEPRECATED; use "ttl" instead.
• ttl optional 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](/docs/config/index.html), or indefinitely if the root policy is used.
• explicit_max_ttl optional 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 optional The display name of the token. Defaults to "token".
• num_uses optional The maximum uses for the given token. This can be used to create a one-time-token or limited use token. Defaults to 0, which has no limit to the number of uses.

Returns

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

/auth/token/lookup[/token]

GET

Description

Returns information about the client token provided in the request path.

Method

GET

URL

`/auth/token/lookup/`

Parameters

None

Returns

```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

POST

Description

Returns information about the client token provided in the request body.

Method

POST

URL

`/auth/token/lookup`

Parameters

• token required Token to lookup.

Returns

```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

/auth/token/lookup-accessor[/accessor]

POST

Description

Fetch the properties of the token associated with the accessor, except the token ID. This is meant for purposes where there is no access to token ID but there is need to fetch the properties of a token.

Method

POST

URL

`/auth/token/lookup-accessor`

Parameters

• accessor required Accessor of the token to lookup. This can be part of the URL or the body.

Returns

```javascript
{
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "creation_time": 1457533232,
    "creation_ttl": 2592000,
    "display_name": "token",
    "id": "",
    "meta": null,
    "num_uses": 0,
    "orphan": false,
    "path": "auth/token/create",
    "policies": ["default", "web"],
    "ttl": 2591976
  },
  "warnings": null,
  "auth": null
}
```

/auth/token/lookup-self

GET

Description

Returns information about the current client token.

Method

GET

Parameters

None

Returns

```javascript
{
  "data": {
    "id": "ClientToken",
    "policies": ["web", "stage"],
    "path": "auth/github/login",
    "meta": {"user": "armon", "organization": "hashicorp"},
    "display_name": "github-armon",
    "num_uses": 0,
  }
}
```

/auth/token/renew[/token]

POST

Description

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

POST

URL

`/auth/token/renew`

Parameters

• token required Token to renew. This can be part of the URL or the body.

• increment optional An optional requested lease increment can be provided. This increment may be ignored.

Returns

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

/auth/token/renew-self

POST

Description

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

POST

URL

`/auth/token/renew-self`

Parameters

• increment optional An optional requested lease increment can be provided. This increment may be ignored.

Returns

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

/auth/token/revoke[/token]

POST

Description

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

Method

POST

URL

`/auth/token/revoke`

Parameters

• token required Token to revoke. This can be part of the URL or the body.

Returns

`204` response code.

/auth/token/revoke-accessor[/accessor]

POST

Description

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

POST

URL

`/auth/token/revoke-accessor`

Parameters

• accessor required Accessor of the token. This can be part of the URL or the body.

Returns

A `204` response code.

/auth/token/revoke-orphan[/token]

POST

Description

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

POST

URL

`/auth/token/revoke-orphan`

Parameters

• token required Token to revoke. This can be part of the URL or the body.

Returns

`204` response code.

/auth/token/revoke-self/

POST

Description

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

Method

POST

URL

`/auth/token/revoke-self`

Parameters

None

Returns

`204` response code.

/auth/token/roles/[role_name]

DELETE

Description

Deletes the named role.

Method

DELETE

URL

`/auth/token/roles/`

Parameters

None

Returns

A `204` response code.

GET

Description

Fetches the named role configuration.

Method

GET

URL

`/auth/token/roles/`

Parameters

None

Returns

```javascript

{ "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec", "lease_id": "", "lease_duration": 0, "renewable": false, "data": { "allowed_policies": [ "dev" ], "disallowed_policies": [], "explicit_max_ttl": 0, "name": "nomad", "orphan": false, "path_suffix": "", "period": 0, "renewable": true }, "warnings": null } ```

LIST

Description

Lists available roles.

Method

GET

URL

`/auth/token/roles?list=true`

Parameters

None

Returns

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

POST

Description

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/revoke-prefix` endpoint.

Method

POST

URL

`/auth/token/roles/`

Parameters

• allowed_policies 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. If this and `disallowed_policies` are both set, only this option takes effect.
• disallowed_policies optional If set, successful token creation via this role will require that no policies in the given list are requested. If both `disallowed_policies` and `allowed_policies` are set, this option has no effect. The parameter is a comma-delimited string of policy names.
• orphan optional 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.
• period optional If set, tokens created against this role will not have a maximum lifetime. Instead, they will have a fixed TTL that is refreshed with each renewal. So long as they continue to be renewed, they will never expire. The parameter is an integer duration of seconds. Tokens issued track updates to the role value; the new period takes effect upon next renew. This cannot be used in conjunction with `explicit_max_ttl`.
• renewable optional Set to `false` to disable the ability of token created against this role to be renewed past their initial TTL. Defaults to `true`, which allows tokens to be renewed up to the system/mount maximum TTL.
• path_suffix optional 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/revoke-prefix`.
• explicit_max_ttl optional If set, tokens created with this role have an explicit max TTL set upon them. This maximum token TTL *cannot* be changed later, and unlike with normal tokens, updates to the role or 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. This cannot be used in conjunction with `period`.

Returns

A `204` return code.