Use API keys to authenticate to Sensu

The Sensu API key feature (core/v2.APIKey) is a persistent universally unique identifier (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.

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" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

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

curl -H "Authorization: Key $SENSU_API_KEY" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

Here’s an example request that uses API key authentication:

curl -H "Authorization: Key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2" http://127.0.0.1:8080/api/core/v2/namespaces/default/checks

A successful request will return the HTTP response code HTTP/1.1 200 OK and the definitions for the checks in the default namespace.

Sensuctl management commands

To use sensuctl to generate a new API key for the admin user, run:

sensuctl api-key grant admin

The response will include the new API key:

Created: /api/core/v2/apikeys/7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2

To bypass username/password authentication for sensuctl, add the --api-key global flag to specify your API key with sensuctl commands. For example:

sensuctl --api-key 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 event list

To get information about an API key:

sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format yaml

sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format wrapped-json

sensuctl api-key info 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2 --format json

The response will include information about the API key in the specified format:

---
type: APIKey
api_version: core/v2
metadata:
  created_by: admin
  name: 7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2
spec:
  created_at: 1570718917
  username: admin

{
  "type": "APIKey",
  "api_version": "core/v2",
  "metadata": {
    "name": "7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2",
    "created_by": "admin"
  },
  "spec": {
    "created_at": 1570718917,
    "username": "admin"
  }
}

{
  "metadata": {
    "name": "7f63b5bc-41f4-4b3e-b59b-5431afd7e6a2",
    "created_by": "admin"
  },
  "username": "admin",
  "created_at": 1570718917
}

To get a list of all API keys:

sensuctl api-key list

The response lists all API keys along with the name of the user who created each key and the date and time each key was created:

                  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

The response will confirm that the API key is deleted:

Deleted