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. Tokens are created on the API Management page, which needs the API management permission (admin.api_management); see API Keys & Playground:

Log in to your Freedam account
Navigate to Admin → API Management and open the Tokens tab
Click Create Application Token
Give your token a descriptive Token Name (required, up to 255 characters) and the Application Name it is for
Optionally add a description (up to 1,000 characters) explaining what the token will be used for
Optionally set an expiry 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 Token
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; admin:full, for example, requires the system settings permission (admin.system_settings). The Create Application Token dialog only lists the scopes you can grant, and a request for a scope that exceeds your own role 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.

Managing tokens through the API

Listing, creating and revoking tokens through the API (GET and POST /v1/tokens, DELETE /v1/tokens/{token}) requires a token holding admin:full. A token with narrower scopes gets 403 Forbidden with "required_abilities": ["admin:full"], so it can neither issue a more powerful token nor revoke your other tokens.

Your role must also still include the API management permission (admin.api_management), the one that opens Admin → API Management. It is checked on every request, so once the permission is removed from your role, even an admin:full token gets 403 Forbidden on these endpoints. You can revoke your own tokens; tenant admins can revoke anyone's.

A token created through the API is also limited by the token that creates it:

It can't receive a scope the requesting token does not hold. admin:full holds every scope listed on this page.
It can't outlive the requesting token. When that token has an expiration date, expires_at is required and must be on or before that date, otherwise the request fails with 422 Unprocessable Entity and an error on expires_at.

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/v1/assets

Example with JavaScript

const response = await fetch('https://your-freedam-instance.com/api/v1/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/v1/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 - Move assets to the Trash
assets:download - Reserved. No current endpoint requires it

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 - Reserved. No current endpoint requires it; asset metadata edits use assets:write

shares:read - View existing share links, their settings and video embed codes
shares:manage - Create, edit, and revoke share links and video embed codes

Analytics

analytics:read - Reserved. No current endpoint requires it

Consents

consents:read - View terms-of-use acceptance status and history. Reading another user's also needs the admin.terms_of_use permission

Webhooks

webhooks:manage - Create and manage your webhook endpoints. It needs no permission of its own, but every subscribed event also needs its own ability, such as assets:read for asset.created (see Webhooks)

Administration

admin:full - Full administrative access to every endpoint, including token management

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. The scope is checked before any id in the path is looked up, so a collection, share or upload batch that does not exist gets the same 403:

{
    "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 Admin → API Management and open the Tokens tab
Find the token in the list
Select Revoke Token, then confirm with 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 with DELETE /v1/tokens/{token}, using a token that holds admin:full; the response confirms 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

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, and X-RateLimit-Reset gives the UNIX timestamp at which the budget refills. Well-behaved clients should respect it and implement exponential backoff for repeated 429s.

Error Handling

Common Error Responses

401 Unauthorized

{
    "message": "Unauthenticated."
}

Solution: Check that your token is valid, not expired or revoked, and included in the Authorization header.

403 Forbidden

A token that lacks the scope of the endpoint gets the body shown in 403 Forbidden with insufficient scopes. A token that holds the scope, but whose user no longer has the permission behind the action, gets:

{
    "message": "This action is unauthorized."
}

Solution: Add the scope listed in required_abilities to the token, or give the token's user the permission for this operation. A token keeps its scopes when a permission is removed from its user's role, so both are checked on every request.

429 Too Many Requests

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

Solution: Wait for the number of seconds in the Retry-After header, and use exponential backoff for repeated 429 responses.

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.