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:

  1. Log in to FireCustos as an administrator of the unit
  2. In the menu, open Administration, API keys
  3. Click "New API key", enter a name that tells you where the key is used and click "Create key"
  4. Copy the key straight away: it is shown only once
Important

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:

bash
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.readRead 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.writeCreate, edit and delete firefighters

A request outside the key's scopes returns 403 Forbidden:

json
{
  "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

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Missing or invalid Authorization header."
}

API key is invalid

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "Invalid API key."
}

API key has been revoked

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "API key has been revoked."
}

API key has expired

json
{
  "status": 401,
  "title": "Unauthorized",
  "detail": "API key has expired."
}