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 cookie for the HTTP API. The name of the cookie should be "token" and the value should be the token.

API

/auth/token/create

POST

Description

Creates a new token. Certain options are only available to when called by a root token.

Method

POST

URL

`/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.
• lease optional The lease period of the token, provided as "1h", where hour is the largest suffix. If not provided, the token is valid for the default lease duration (30 days), 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-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/

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.

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