Authentication API

The /auth API endpoint

/auth (GET)

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

EXAMPLE

In the following example, querying the /auth API endpoint with a given username and password returns an HTTP 200 OK response to indicate that the credentials are valid, along with an access token and a refresh token.

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

HTTP/1.1 200 OK
{
  "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 see 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)

The /auth/test API endpoint

/auth/test (GET)

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 provider. It does not test user credentials defined via an authentication provider like Lightweight Directory Access Protocol (LDAP) or Active Directory (AD).

EXAMPLE

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

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

HTTP/1.1 200 OK

API Specification

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

The /auth/token API endpoint

/auth/token (POST)

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 and returns a successful HTTP 200 OK response along with the new access token.

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

HTTP/1.1 200 OK
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1544582187,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

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)