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 .