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/create[-orphan]

POST

Description

Creates a new token. Certain options are only available to 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).

Method

POST

URL

`/auth/token/create[-orphan]`

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.
• 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.
• 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 number of uses.

Returns

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

/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/lookup/

GET

Description

Returns information about the current client token.

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,
  }
}
```

/auth/token/revoke/

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

None

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/revoke-orphan/

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/`.

Method

POST

URL

`/auth/token/revoke-orphan/`

Parameters

None

Returns

`204` response code.

/auth/token/revoke-prefix/

POST

Description

Revokes all tokens generated at a given prefix, along with child tokens, and all secrets generated using those tokens. Uses include revoking all tokens generated by a credential backend during a suspected compromise.

Method

POST

URL

`/auth/token/revoke-prefix/`

Parameters

None

Returns

`204` response code.

/auth/token/renew-self

POST

Description

Renews a lease associated with the callign 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/renew/

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

• 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,
  }
}
```