Access to the Phoenix Security REST API is controlled by API Client ID and Secret. However, requests to the API endpoints are not individually authenticated by those credentials. Instead, clients must use their ID and Secret to obtain time-limited access tokens – then they can use the access token to authenticate each API request.
The API domain for Production is https://api.securityphoenix.cloud (not included in the paths below). If you are using a different environment to Production please contact your Phoenix team for the correct API domain.
Client ID and Secret
Customers can generate one or more sets of API credentials in the Phoenix Security platform (Settings > Organisation > API Access). Each of those sets can be managed independently so that potentially compromised credentials can be deactivated or removed from the platform.
When users create API credentials in the UI they will only be able to see and copy the API Secret at the time of creation. This secret is stored in an encrypted form and can’t be decrypted again. It’s important that users copy and safely store the secret at the time of creation.
The Client ID is a “username” that allows for identification of the secret that needs to be checked – it can be stored in clear text for easy lookup. The Client Secret should be stored in an encrypted (hashed) format so that it’s not possible to decrypt it but it’s possible to check if a clear text string matches the encrypted secret – like it works with password storage and check.
Obtaining Access Tokens
Before clients can make requests to the API they need to obtain an Access Token. In order to do so, clients need to send a request to the tokens endpoint and include an HTTP Basic Auth header with the Client ID (username) and Secret (password).
GET /v1/auth/access_token
Headers:
Authorization: Basic <username = client ID; password = secret>Responses
Incorrect credentials: 401 Unauthorized
Correct credentials: 200 OK
{
"token": string,
"expiry": number // Time of token expiration as Unix timestamp
}- token: An opaque (Bearer) token to be included in subsequent requests to the API.
- expiry: The time of expiration of the token in Unix timestamp format. Due to server time shift, clients should not rely on this timestamp alone, and should handle “token invalid or expired” responses as appropriate.
Using Access Tokens
All requests to the Phoenix Security API – except for the /v1/access_token endpoint above – should include an access token as part of the request. This is done through an Authorization/Bearer HTTP header.
Authorization: Bearer <access token>If the token is missing, it’s incorrect or it has expired, the request would return an 401 Unauthorized code. The response body might, or might not, contain additional details.
