Use API keys to authenticate to Sensu

The Sensu API key feature (core/v2.APIKey) is a persistent UUID that maps to a stored Sensu username. The advantages of authenticating with API keys rather than access tokens include:

  • More efficient integration: Check and handler plugins and other code can integrate with the Sensu API without implementing the logic required to authenticate via the /auth API endpoint to periodically refresh the access token
  • Improved security: API keys do not require providing a username and password in check or handler definitions
  • Better admin control: API keys can be created and revoked without changing the underlying user’s password…but keep in mind that API keys will continue to work even if the user’s password changes

API keys are cluster-wide resources, so only cluster admins can grant, view, and revoke them.

NOTE: API keys are not supported for authentication providers such as LDAP and OIDC.

API key authentication

Similar to the Bearer [token] Authorization header, Key [api-key] will be accepted as an Authorization header for authentication.

For example, a JWT Bearer [token] Authorization header might be:

curl -H "Authorization: Bearer $SENSU_ACCESS_TOKEN"

If you’re using Key [api-key] to authenticate instead, the Authorization header might be:

curl -H "Authorization: Key $SENSU_API_KEY"


$ curl -H "Authorization: Key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2"

HTTP/1.1 200 OK
    "command": " -w 75 -c 90",
    "handlers": [
    "interval": 60,
    "publish": true,
    "subscriptions": [
    "metadata": {
      "name": "check-cpu",
      "namespace": "default"

Sensuctl management commands

NOTE: The API key resource is intentionally not compatible with sensuctl create.

To generate a new API key for the admin user:

$ sensuctl api-key grant admin
Created: /api/core/v2/apikeys/7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2

To get information about an API key:

$ sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format json
  "metadata": {
    "name": "7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2"
  "username": "admin",
  "created_at": 1570744117

To get a list of all API keys:

$ sensuctl api-key list
                  Name                   Username            Created At            
 ────────────────────────────────────── ────────── ─────────────────────────────── 
  7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2   admin      2019-10-10 14:48:37 -0700 PDT

To revoke an API key for the admin user:

$ sensuctl api-key revoke 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --skip-confirm