Tokens endpoints

Parameters

You must use at least one of these parameters to specify tokens:

/tokens?revoke_tokens_by_usernames=<USER NAME>,<USER NAME>
Copied!

{"revoke_tokens_by_usernames": ["<USER NAME>", "<USER NAME>"]}
Copied!

If you supply a parameter as both a query parameter and in the 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.

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. For example, you would have multiple errors if the request included some malformed usernames and a database error occurred when trying to revoke the well-formed usernames.

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

Any user can revoke any token by supplying the complete token in the revoke_tokens query parameter or request body field.

To revoke tokens by username, the user making the request must have the Users Revoke permission for that user.

Example JSON body

{"revoke_tokens": ["eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJhZG1pbiIsImlhdCI6MTQzOTQ5Mzg0NiwiZXhwIjoxNDM5NDk0MTQ2LCJzdWIiOnsibG9naW4iOiJhZG1pbiIsImlkIjoiNDJiZjM1MWMtZjllYy00MGFmLTg0YWQtZTk3NmZlYzdmNGJkIn19.gCXZVMJ1TwRKMKCV3OESK-tMGtAALp_vBONSQQ2zU5ihWfsDU4mmmefbelR1CzA2TWrsv62DpJhtSc3iMLsSyjcUjsP6I87kjw3XFtjcB79kx5G0olhReEzkZ9wsvoR3Ha55VD2LEhfoUl8Q0jqlGRCnWUsbUeORYLkBpWpyOkbgww1UZXBLCcdMIxVcxa4xfDdGCcRT_dIB7tEtkHWH_DgA2Hbc3AMhE_9S1T_W563y9ObD58lPgFNMFr2qkFjVLQpDkKnQF1AaCDHIj-aODfSvzf9l35IE7vi97s-9fFcHUFPzboyz60GDyRJVSOwohTWpNJMlAfx0UBitgqCYXnE4rr8wKBoeOXoeEQezJZ1MJlQdi9cMzqB7t2i02uHJWmnVKio4WM1BukikjXtftnLIcJiQwpnENnXS9WmaIhpFTuKqeXRJbRN979HTEmGTArdQMpllE-u8-q0TqeN3ke4azDxdIqfhZ7H10-jDR0C5yeSBGWfX-0KEbp42cGz8lA6rrIHpSaajRWUg9yTHeUkT2crh6878orCLgfoBLDh-rOBTLeIua16sasH-ggpdHqVkTFOomEXM6UTJlp1NpuP01rNr9JMlxWhI8WpExH1l_-136D1NJm32kwo-oV6GzXRx70xq_N2CwIwObw-X1S5aUUC4KkyPtDmNvnvC1n4"]
    "revoke_tokens_by_labels": ["Workstation Token", "VPS Token"],
    "revoke_tokens_by_usernames": ["<USER NAME>", "<USER NAME>"]}Copied!

Response codes

All error responses follow the standard JSON error format, meaning they have kind, msg, and details keys.

The kind key is puppetlabs.rbac/database-token-error for a 500 response, permission-denied for a 403 response, and malformed-token-request for a 400 response.

The msg key contains an English-language description of the problems encountered while processing the request and performing the revocations. It ends with either No tokens were revoked or All other tokens were successfully revoked, depending on whether any operations were successful.

The details key contains an object with arrays in the malformed_tokens, malformed_usernames, malformed_labels, nonexistent_usernames, permission_denied_usernames, unrecognized_parameters, malformed_ids, and permission_denied_ids fields, as well as the Boolean field other_tokens_revoked. The arrays all contain bad input from the request, and the other_tokens_revoked field's value indicates whether any of the revocations specified in the request were successful or not.

Example error body

{"kind": "malformed-request",
 "msg": "The following user does not exist: FormerEmployee. All other tokens were successfully revoked.",
 "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}}Copied!

This endpoint is equivalent to DELETE /tokens?revoke_tokens={TOKEN}.

Only admins or API users can use this endpoint.

Response codes

The server uses these response codes:

Error response

This endpoint's error response is identical to DELETE /tokens.

{
 "kind": "malformed-request",
 "msg": "The following token is malformed: notAToken. This can be caused by an error while copying and pasting. No tokens were revoked."
 "details": {"malformed_tokens": ["notAToken"],
             "malformed_labels": [],
             "malformed_usernames": [],
             "nonexistent_usernames": [],
             "permission_denied_usernames": [],
             "unrecognized_parameters": [],
             "other_tokens_revoked": false}
}Copied!

This endpoint accepts a JSON body containing entries for token and update_last_activity?. The token field is a string containing an authentication token. The update_last_activity? field is a Boolean data type indicating whether you want successful authentication to update the last_active timestamp for the token.

Response codes

The server uses these response codes:

Example JSON body

{
 "token": "0VZZ6geJQK8zJGKxBdq1atTsMLAsfCQFJuRwxsMNgCr4",
 "update_last_activity?": false
}
Copied!

Example return

{
 "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
}Copied!