API Authentication

The Freedam API uses token-based authentication to secure API requests.

Getting an API Token

To use the Freedam API, you'll need an API token:

Log in to your Freedam account
Navigate to Settings → API Tokens
Click Create New Token
Give your token a descriptive name (required, up to 255 characters)
Optionally add a description (up to 1,000 characters) explaining what the token will be used for
Optionally set an expiration date — if set, it must be in the future; leaving it empty creates a non-expiring token
Select the scopes (abilities) the token should have — you must pick at least one
Click Create
Copy the token (the full token string is returned only once at creation time — there is no way to retrieve it later)

The server only stores a hashed version of the token, which is why it cannot be displayed a second time. If you lose it, revoke the token and create a new one.

Scope elevation safeguard

You can only grant a token scopes you personally have permission to use. If you ask for a scope that exceeds your own role, the request is rejected with a 403 Forbidden response that lists the specific scopes that were refused:

{
    "message": "You do not have the required permissions to grant these abilities.",
    "unauthorized_abilities": ["assets:delete", "admin:full"]
}

This means a token can never be more privileged than the person who created it.

Making Authenticated Requests

Include your API token in the Authorization header of each request:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://your-freedam-instance.com/api/assets

Example with JavaScript

const response = await fetch('https://your-freedam-instance.com/api/assets', {
    headers: {
        Authorization: 'Bearer YOUR_API_TOKEN',
        Accept: 'application/json',
        'Content-Type': 'application/json',
    },
});

const data = await response.json();

Example with Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Accept': 'application/json'
}

response = requests.get(
    'https://your-freedam-instance.com/api/assets',
    headers=headers
)

data = response.json()

Token Permissions (Scopes)

Every token is granted one or more abilities (also called scopes). Each endpoint requires a specific ability, and a request is rejected with 403 Forbidden if the token is missing it. Below is the full list of abilities you can assign, grouped by area.

Assets

assets:read — View assets, their metadata, and previews
assets:write — Edit asset metadata and properties
assets:delete — Soft-delete and restore assets
assets:download — Download original files and renditions

Collections

collections:read — View collections and their contents
collections:write — Create and edit collections, add or remove assets
collections:delete — Delete collections

Uploads

uploads:manage — Create upload batches, upload files, and check batch status

Metadata

metadata:read — Read metadata definitions, vocabularies, and terms
metadata:write — Modify metadata field values on assets

shares:read — View existing share links and their settings
shares:manage — Create, edit, and revoke share links

Analytics

analytics:read — View system analytics and usage metrics

Consents

consents:read — View terms-of-use acceptance audit trail

Administration

admin:full — Full administrative access to every endpoint

Admin-scope bypass

A token holding admin:full is accepted anywhere an ability check runs, even if it was not issued the specific scope. Use this sparingly — prefer narrow scopes for day-to-day integrations and keep admin:full for trusted automation run by platform administrators.

403 Forbidden with insufficient scopes

When a token is authenticated but lacks the required scope, the response includes the exact scopes that the endpoint demanded, so you know what to add when you rotate the token:

{
    "message": "Token does not have the required abilities.",
    "required_abilities": ["assets:write"]
}

Token Security

Best Practices

Never share tokens - Each application should have its own token
Use minimal permissions - Only grant permissions needed for the task
Rotate tokens regularly - Create new tokens and revoke old ones periodically
Store securely - Never commit tokens to version control

Revoking Tokens

If a token is compromised:

Navigate to Settings → API Tokens
Find the token in the list
Click Revoke
Create a new token if needed

Revocation is instant: once a token is revoked, the next request using it will be rejected with 401 Unauthorized. There is no grace period. You can also revoke a token programmatically from an authenticated client; the response will confirm the revocation.

Audit Trail

Every authenticated API request is recorded for security and compliance review. For each call, the following is captured:

The user and token that made the request (token name is stored alongside the token ID so revoked tokens remain identifiable)
The HTTP method and path
The resulting status code and response time in milliseconds
The client IP address
The resource type and, when applicable, the specific resource ID acted on

Each token also stores the last IP address it was used from and the last used timestamp, both visible on the token list. A token that suddenly starts calling from an unexpected location is easy to spot and revoke.

Rate Limiting

Every authenticated API request is counted against a per-token limit of 60 requests per minute. The limit is keyed on the token itself, so two different tokens belonging to the same user each get their own independent budget.

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

Handling Rate Limits

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
    "message": "API rate limit exceeded. Please try again later."
}

The Retry-After header on the response tells you how many seconds to wait before making another request. Well-behaved clients should respect it and implement exponential backoff for repeated 429s.

Error Handling

Common Error Responses

401 Unauthorized

{
    "error": "Unauthenticated",
    "message": "Invalid or missing API token"
}

Solution: Check that your token is valid and included in the Authorization header.

403 Forbidden

{
    "error": "Forbidden",
    "message": "Insufficient permissions"
}

Solution: Verify your token has the required permissions for this operation.

429 Too Many Requests

{
    "error": "Too many requests",
    "retry_after": 30
}

Solution: Implement exponential backoff and respect rate limits.

Next Steps

API Endpoints — Browse the full v1 endpoint catalogue.
Webhooks — Subscribe to real-time events with signed payloads.
Rate Limiting — Per-token budget, response headers, and back-off contract.
Official SDKs — Install @freedam/sdk or generate a client from the OpenAPI spec.