/auth

Generate an access token and a refresh token

The /auth API endpoint provides HTTP GET access to generate an access token and a refresh token using Sensu’s basic authentication.

The access and refresh tokens are JSON Web Tokens (JWTs) that Sensu issues to record the details of users’ authenticated Sensu sessions. The backend digitally signs these tokens, and the tokens can’t be changed without invalidating the signature.

Example

The following example queries the /auth API endpoint with a given username and password to determine whether the credentials are valid and retrieve an access token and a refresh token:

curl -X GET \
http://127.0.0.1:8080/auth \
-u myusername:mypassword

The request results in a successful HTTP/1.1 200 OK response to indicate that the credentials are valid, along with an access token and a refresh token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

API Specification

/auth (GET)
description Generates an access and a refresh token used for accessing the API using Sensu’s basic authentication. Access tokens last for approximately 15 minutes. When your token expires, you should receive a 401 Unauthorized response from the API. To generate a new access token, use the /auth/token API endpoint.
example url http://hostname:8080/auth
output 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
response codes
  • Valid credentials: 200 (OK)
  • Invalid credentials: 401 (Unauthorized)
  • Error: 500 (Internal Server Error)

Test basic auth user credentials

The /auth/test API endpoint provides HTTP GET access to test basic authentication user credentials that were created with Sensu’s built-in basic authentication.

NOTE: The /auth/test endpoint only tests user credentials created with Sensu’s built-in basic authentication. It does not test user credentials defined via an authentication provider like Lightweight Directory Access Protocol (LDAP), Active Directory (AD), or OpenID Connect 1.0 protocol (OIDC).

Example

In the following example, querying the /auth/test API endpoint with a given username and password should return an HTTP/1.1 200 OK response, indicating that the credentials are valid:

curl -X GET \
http://127.0.0.1:8080/auth/test \
-u myusername:mypassword

API Specification

/auth/test (GET)
description Tests basic authentication credentials (username and password) that were created with Sensu’s core/v2/users API.
example url http://hostname:8080/auth/test
response codes
  • Valid credentials: 200 (OK)
  • Invalid credentials: 401 (Unauthorized)
  • Error: 500 (Internal Server Error)

Renew an access token

The /auth/token API endpoint provides HTTP POST access to renew an access token.

Example

In the following example, an HTTP POST request is submitted to the /auth/token API endpoint to generate a valid access token. The request includes the refresh token in the request body.

curl -X POST \
http://127.0.0.1:8080/auth/token \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H 'Content-Type: application/json' \
-d '{"refresh_token": "eyJhbGciOiJIUzI1NiIs..."}'

The request results in a successful HTTP/1.1 200 OK response, along with the new access token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

The access and refresh tokens are JSON Web Tokens (JWTs) that Sensu issues to record the details of users’ authenticated Sensu sessions. The backend digitally signs these tokens, and the tokens can’t be changed without invalidating the signature.

API Specification

/auth/token (POST)
description Generates a new access token using a refresh token and an expired access token.
example url http://hostname:8080/auth/token
example payload 
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
output 
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
response codes
  • Success: 200 (OK)
  • Malformed: 400 (Bad Request)
  • Error: 500 (Internal Server Error)