Tokens endpoints

Authentication tokens control access to PE services. Use the v2 tokens endpoints to revoke and validate tokens.

You can use the v1 Tokens endpoints to create tokens.

DELETE /tokens

Use this endpoint to revoke one or more authentication tokens, ensuring the tokens can no longer be used with RBAC to access PE services.

Request format

When Forming RBAC API requests to this endpoint, your request must use at least one of these query parameters to specify the tokens you want to revoke:
  • revoke_tokens: Supply a list of complete authentication tokens you want to revoke. Any user can revoke any token by supplying the complete token in this parameter.
  • revoke_tokens_by_usernames: Supply a list of user names identifying users whose tokens you want to revoke. To revoke tokens by user name, the user making the request must have the Users Revoke permission for the specified users.
  • revoke_tokens_by_labels: Supply a list of labels identifying tokens to revoke. To be revoked in this manner, the tokens must belong to the requesting user and have been assigned a token-spcific label.
  • revoke_tokens_by_ids: Supply a list of UUIDs for users whose tokens you want to revoke. To revoke tokens by user name, the user making the request must have the Users Revoke permission for the specified users.

You can append the parameters to the URI path, supply a JSON-encoded body, or both.

For example, this request uses an appended query parameter.
curl -X DELETE "https://$(puppet config print server):4433/rbac-api/v2/tokens?revoke_tokens_by_usernames=<USER_NAME>,<USER_NAME>" \
-H "X-Authentication:$(puppet-access show)"
When supplying parameters in a JSON-encoded body, specify the content type as application/json, format the entire body as a JSON object, and format each value list as an array. For example:
curl -X DELETE "https://$(puppet config print server):4433/rbac-api/v2/tokens" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"revoke_tokens": ["<TOKEN>", "TOKEN"],
    "revoke_tokens_by_labels": ["Workstation Token", "VPS Token"],
    "revoke_tokens_by_usernames": ["<USER_NAME>", "<USER_NAME>"]}'

When supplying multiple values, use commas to separate tokens, labels, user names, and IDs.

If you supply values by appending parameters and in a JSON body, the values from the both sources are combined.

It is not an error to specify the same token using multiple means. For example, you could supply the entire token to the revoke_tokens parameter and also include its label in the value of revoke_tokens_by_labels.

All operations on this endpoint are idempotent. It is not an error to revoke the same token multiple times.

Response format

The server sends a 204 No Content response if all operations succeed.

Error responses

In the case of an error, malformed input, or bad request data, the endpoint still attempts to revoke as many tokens as possible. This means it's possible to encounter multiple error conditions in a single request while some requested operations succeed. For example, you would get multiple errors if a request included some malformed user names and a database error occurred when trying to revoke the well-formed user names.

Error codes include:
  • 500 Application Error: There was a database error when trying to revoke tokens.
  • 403 Forbidden: The user lacks permission to revoke one of the supplied user names and no database error occurred.
  • 400 Malformed: One of these conditions is true:
    • At least one of the tokens, user names, labels, or IDs is malformed.
    • At least one of the user names or IDs does not exist in the RBAC database.
    • The request contains no parameters or values to revoke.
    • The request contains illegal parameters.
In the error response, the msg key contains information about encountered errors and either No tokens were revoked or All other tokens were successfully revoked, depending on whether any operations were successful. For example:
"msg": "The following user does not exist: FormerEmployee. All other tokens were successfully revoked."
The error response also returns unprocessed or erroneous values in the details key in the error response. For example, this response had one failed operation and succeeded in all other operations:
{"kind": "malformed-request",
 ,
 "details": {"malformed_tokens": [],
             "malformed_labels": [],
             "malformed_usernames": [],
             "malformed_ids": [],
             "nonexistent_usernames": ["FormerEmployee"],
             "permission_denied_usernames": [],
             "permission_denied_ids": [],
             "unrecognized_parameters": [],
             "permission_denied_usernames": []
             "unrecognized_parameters": []
             "other_tokens_revoked": true}}
Error categories include:
  • malformed_tokens, malformed_usernames, malformed_labels, and malformed_ids: Contain any values from the request that aren't properly formatted as tokens, user names, labels, or UUIDs.
  • nonexistent_usernames: Contains any value from the revoke_tokens_by_usernames parameter that doesn't match an existing user's user name.
  • permission_denied_usernames and permission_denied_ids: The requesting user doesn't have permission to revoke tokens for users identified in these arrays.
  • unrecognized_parameters: The request contained an invalid or malformed parameter.
The other_tokens_revoked Boolean indicates whether any non-erroneous values were successfully revoked.

For more information about RBAC API errors and errors not described here, refer to RBAC service errors.

DELETE /tokens/<token>

Use this endpoint to revoke a single token, ensuring that it can no longer be used with RBAC. Authentication is required.

Request format

Only admins or API users can use this endpoint.

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication and a single token specified in the URI path. For example:
curl -X DELETE "https://$(puppet config print server):4433/rbac-api/v2/tokens/<TOKEN>" \
-H "X-Authentication:$(puppet-access show)"
Tip: This endpoint is equivalent to using the DELETE /tokens endpoint with the revoke_tokens parameter and a single token value. If you're not an admin, try the DELETE /tokens route for revoking tokens.

Response format

The server returns 204 No Content if the revocation was successful.

Error responses

Error response are similar to DELETE /tokens error responses, except that only one token is processed.

POST /auth/token/authenticate

Use this endpoint to exchange a token for a map representing an RBAC subject and associated token data. Authentication isn't required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using these keys:
  • token: An authentication token
  • update_last_activity?: A Boolean indicating whether you want a successful request to update the token's last_active timestamp.
For example:
curl -X POST "https://$(puppet config print server):4433/rbac-api/v2/auth/token/authenticate" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{
     "token": "<TOKEN>",
     "update_last_activity?": false
    }'

Response format

A successful request returns a 200 OK response and JSON object representing the RBAC subject and associated token data, such as:
{
 "description":null,
 "creation":"YYYY-MM-DDT22:24:30Z",
 "email":"franz@kafka.com",
 "is_revoked":false,
 "last_active":"YYYY-MM-DDT22:24:31Z",
 "last_login":"YYYY-MM-DDT22:24:31.340Z",
 "expiration":"YYYY-MM-DDT22:29:30Z",
 "is_remote":false,
 "client":null,
 "login":"franz@kafka.com",
 "is_superuser":false,
 "label":null,
 "id":"c84bae61-f668-4a18-9a4a-5e33a97b716c",
 "role_ids":[1, 2, 3],
 "user_id":"c84bae61-f668-4a18-9a4a-5e33a97b716c",
 "timeout":null,
 "display_name":"Franz Kafka",
 "is_group":false
}

For information about keys describing the user, refer to Users endpoints keys. For information about keys describing the token, refer to Tokens endpoints keys.

Error responses

Invalid requests return these errors:
  • 400 invalid-token: The provided token was either tampered with or could not be parsed.
  • 403 token-revoked: The provided token has been revoked.
  • 403 token-expired: The token has expired and is no longer valid.
  • 403 token-timed-out: The token has timed out due to inactivity.

For other errors, refer to RBAC service errors.