API Tokens

API tokens provide authentication for external integrations and automated systems that need to access the FullFabric API without a user session. Tokens are managed by staff or admin users and have their own lifecycle with states, expiration, and audit tracking.

Token Format

API tokens use a sk- prefix followed by an optional name and a cryptographic random string:

sk-hubspot-integration-a1b2c3d4e5f6...
sk-reporting-api-x9y8z7w6v5u4...
sk-a1b2c3d4e5f6g7h8i9j0...

The full token is shown only once at creation time. After that, it is displayed in obfuscated form (e.g., sk-hubspot-int... xyz). Store the token securely when it is first created.

Token Lifecycle

Each token has a state that controls whether it can be used:

stateDiagram-v2
    [*] --> active: Created
    active --> suspended: Admin suspends
    suspended --> active: Admin reactivates
    active --> revoked: Admin revokes
    suspended --> revoked: Admin revokes
    active --> expired: Past expiry date

State	Description	Can authenticate?
Active	Token is functional and accepting requests	Yes
Suspended	Temporarily disabled by an administrator	No
Revoked	Permanently disabled — cannot be reactivated	No
Expired	Automatically disabled when past its expiry date	No

State Transitions

Suspend: Temporarily disable a token. Useful when investigating suspicious activity or during maintenance. Can be reactivated.
Reactivate: Re-enable a suspended token.
Revoke: Permanently disable a token. This cannot be undone — create a new token if needed.
Expire: Happens automatically when a token's expiry date passes. Also cannot be undone.

Each state transition records the timestamp and the user who performed the action.

Expiration

Tokens can optionally have an expiry date set at creation time. Expiration is checked on every request — if the token is past its expiry date, it is automatically transitioned to the expired state.

Expiry Reminders

FullFabric sends email reminders before a token expires:

Reminder	When
14-day notice	14 days before expiry
7-day notice	7 days before expiry
3-day notice	3 days before expiry
1-day notice	1 day before expiry
Expired notice	On the day of expiry

Each reminder is sent only once (tracked per token to prevent duplicates).

Token Permissions

API tokens have minimal permissions compared to user accounts. Currently, tokens are granted only:

core.core.files_download — Download files via the API

Tokens cannot:

Access staff or admin features
Create, update, or delete resources
Impersonate users or access restricted data

This limited permission set means API tokens are suitable for read-only integrations and file downloads. For broader API access, future updates may expand token capabilities.

Using API Tokens

To authenticate an API request with a token, include it in the FF_AUTH HTTP header:

GET /api/resource HTTP/1.1
Host: institution.fullfabric.com
FF_AUTH: sk-your-token-here

The token can also be passed as a token query parameter, but the header method is recommended for security.

The API returns a FF-Auth-Token-Valid-Until header in responses, indicating when the token will expire (if an expiry date is set).

Managing Tokens

Who Can Manage Tokens

Only staff or admin users with the core.institutions.settings_api_tokens_change feature can create and manage API tokens.

Creating a Token

Navigate to Settings > API Tokens.
Click Create Token.
Provide a name and optional description and expiry date.
Copy the full token immediately — it will not be shown again.

Suspending, Reactivating, or Revoking

From the API Tokens settings page, select a token and choose the appropriate action. Suspended tokens can be reactivated; revoked tokens cannot.

SSO / SAML