Tokens endpoints

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.

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>"]}'

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.

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)"

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
    }'

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
}

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.