diff --git a/website/source/docs/auth/token.html.md b/website/source/docs/auth/token.html.md index dbbc80083..3676ee17c 100644 --- a/website/source/docs/auth/token.html.md +++ b/website/source/docs/auth/token.html.md @@ -9,7 +9,7 @@ description: |- # 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 +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. @@ -35,9 +35,287 @@ $ vault auth #### Via the API -The token is set directly as a cookie for the HTTP API. See the -[HTTP API](/docs/http/index.html) documentation for more information. +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 -For API documentation on the token store, see `vault help auth/token`. +## /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. +
    • +
  • + metadata + 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 indefinitely. +
    • +
  • + 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 orpahaned, 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, + } + } + ``` +
+
+ diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 9e04155fc..f969ea15b 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -128,7 +128,7 @@ Auth Backends