API keys reference

API keys are long-lived authentication tokens that make it more convenient for Sensu plugins and other Sensu-adjacent applications to authenticate with the Sensu API. Unlike authentication tokens, API keys are persistent and do not need to be refreshed every 15 minutes.

The Sensu backend generates API keys, and you can provide them to applications that want to interact with the Sensu API.

Use the core/v2/apikeys API endpoints to create, retrieve, and delete API keys.

API key example

This example shows an APIKey resource definition:

---
type: APIKey
api_version: core/v2
metadata:
  name: 19803eb8-36a6-4203-a225-28ec4e9f4444
spec:
  created_at: 1570732266
  username: admin
{
  "type": "APIKey",
  "api_version": "core/v2",
  "metadata" : {
    "name": "19803eb8-36a6-4203-a225-28ec4e9f4444"
  },
  "spec": {
    "created_at": 1570732266,
    "username": "admin"    
  }
}

Authorization header format

Use the following header format to authenticate with API keys, replacing <API_KEY> with your API key:

Authorization: Key <API_KEY>

This is different from the authentication token, which uses the Authorization: Bearer header format.

When you specify an API key in a request, the system resolves it to an authentication token and continues through the regular authentication process.

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

API key specification

Top-level attributes

api_version
description Top-level attribute that specifies the Sensu API group and version. The api_version should always be core/v2.
required true
type String
example 
api_version: core/v2
{
  "api_version": "core/v2"
}
metadata
description Top-level collection of metadata about the API key, including name and created_by. The metadata map is always at the top level of the API key definition. This means that in wrapped-json and yaml formats, the metadata scope occurs outside the spec scope.
required true
type Map of key-value pairs
example 
metadata:
  name: 19803eb8-36a6-4203-a225-28ec4e9f4444
  created_by: admin
{
  "metadata": {
    "name": "19803eb8-36a6-4203-a225-28ec4e9f4444",
    "created_by": "admin"
  }
}
spec
description Top-level map that includes the API key’s spec attributes.
required true
type Map of key-value pairs
example 
spec:
  created_at: 1570732266
  username: admin
{
  "spec": {
    "created_at": 1570732266,
    "username": "admin"
  }
}
type
description Top-level attribute that specifies the resource type. API keys should always be type APIKey.
required true
type String
example 
type: APIKey
{
  "type": "APIKey"
}

Metadata attributes

created_by
description Username of the Sensu user who created the API key or last updated the API key. Sensu automatically populates the created_by field when the API key is created or updated.
required false
type String
example 
created_by: admin
{
  "created_by": "admin"
}
name
description Unique string used to identify the API key. Sensu randomly generates a universally unique identifier (UUID) for the name value — users cannot provide a name for an API key.
required true
type String
example 
name: 19803eb8-36a6-4203-a225-28ec4e9f4444
{
  "name": "19803eb8-36a6-4203-a225-28ec4e9f4444"
}

Spec attributes

created_at
description Time at which the API key was created. Unix timestamp that is automatically generated when the API key is created.
required true
type Integer
example 
created_at: 1234567890
{
  "created_at": 1234567890
}
username
description User associated with the API key.
required true
type Array
example 
username: admin
{
  "username": "admin"
}