Authentication
Learn how to authenticate your API requests using API keys.
Overview #
The FireCustos API uses API key authentication. Every request must include a valid API key in the Authorization header.
Creating API keys #
An administrator of the unit creates API keys in FireCustos:
- Log in to FireCustos as an administrator of the unit
- In the menu, open Administration, API keys
- Click "New API key", enter a name that tells you where the key is used and click "Create key"
- Copy the key straight away: it is shown only once
API keys are prefixed with fc_ and are 68 characters long. The full key is displayed only once at creation — store it securely immediately.
Using API Keys #
Include the API key in the Authorization header as a Bearer token:
curl -X GET https://app.firecustos.com/api/v1/firefighters \
-H "Authorization: Bearer fc_your_api_key_here" What a key can do #
Every key carries scopes that decide what it may do. A key with no scopes selected is read-only. Scopes can be changed at any time and apply from the next request.
| Scope | |
|---|---|
api:firefighters.read | Read the firefighter list. For each member: first and last name, phone, email, date of birth, rank, membership category, functions, number of interventions and competencies, whether they have an account and until when they are unavailable |
api:firefighters.write | Create, edit and delete firefighters |
A request outside the key's scopes returns 403 Forbidden:
{
"status": 403,
"title": "Forbidden",
"detail": "You are not authorized to perform this action."
} Security #
API keys are sensitive credentials. Follow these best practices:
- Never share API keys in public repositories or client-side code
- Use environment variables to store keys
- Replace keys from time to time: create a new one, then revoke the old one
- Each key is hashed with SHA-256 before it is stored, so FireCustos never stores your key in plain text
- Set expiration dates on keys when possible
Authentication Errors #
When authentication fails, the API returns a 401 Unauthorized response:
No API key provided
{
"status": 401,
"title": "Unauthorized",
"detail": "Missing or invalid Authorization header."
} API key is invalid
{
"status": 401,
"title": "Unauthorized",
"detail": "Invalid API key."
} API key has been revoked
{
"status": 401,
"title": "Unauthorized",
"detail": "API key has been revoked."
} API key has expired
{
"status": 401,
"title": "Unauthorized",
"detail": "API key has expired."
}