Authentication

FiscalAPI uses Bearer token authentication with API keys.

API key format

API keys follow the format:

fsk_{environment}_{64 hex characters}

Prefix	Environment	Usage
fsk_test_	Test	Development and testing
fsk_live_	Live	Production

Using your API key

Include the API key in the Authorization header:

curl https://api.fiscalapi.com/v1/locations \
  -H "Authorization: Bearer fsk_test_abc123def456..."

Key lifecycle

1. Creation: An API key is generated when you create an account. The plaintext key is returned only once.
2. Storage: FiscalAPI stores a SHA-256 hash of the key. The plaintext cannot be retrieved after creation.
3. Revocation: Keys can be revoked, making them permanently unusable.

caution

Store your API key securely immediately after account creation. If lost, you'll need to generate a new key.

Test vs live mode

The API key prefix determines the environment for each request:

• fsk_test_ keys route fiscalization to sandbox tax authority endpoints. Use these during development and testing.
• fsk_live_ keys route fiscalization to production tax authority endpoints. Requires the server to have live mode enabled.

Transactions include an environment field ("test" or "live") reflecting which mode was used.

If live mode is not enabled on the server, requests with fsk_live_ keys return 403 Forbidden:

{
  "error": "live mode is not enabled"
}

See the Sandbox routing guide for more details.

Public endpoints

The following endpoints do not require authentication:

Endpoint	Description
GET /health	Service health check
GET /version	API version information
POST /v1/accounts	Account creation

Error responses

Status	Error	Cause
401	missing or invalid Authorization header	No Authorization header provided
401	invalid API key format	Key doesn't match expected format
401	invalid API key	Key not found or hash mismatch
401	API key has been revoked	Key was revoked
403	account is not active	Account suspended or cancelled

Example error response:

{
  "error": "missing or invalid Authorization header"
}

Best practices

• Use fsk_test_ keys for development; never use fsk_live_ keys in test environments
• Store keys in environment variables, not in code
• Rotate keys periodically by creating new ones and revoking old ones
• Use separate keys for different services or environments