Authentication & Authorization

Authenticate with FastFollow

FastFollow is multi-tenant by design. Every API request is scoped to a tenant, a user, and a role — with fine-grained permissions on top. This page covers session tokens, API tokens, OAuth, and the RBAC model.

Create an account API reference

Authentication methods

Three supported ways to authenticate

Session cookies (browser)

Used by the FastFollow web app. Short-lived JWT access tokens stored in memory + long-lived refresh tokens in httpOnly cookies. Automatic rotation.

For interactive users in a browser

API tokens (server-to-server)

Long-lived bearer tokens generated from /settings → API Tokens. Scoped to a specific tenant and role. Use for backend automations, cron jobs, scripts.

For machine clients and integrations

OAuth 2.0 with Google

For human users who prefer SSO

API token quickstart

Generate a token, then authenticate every request with it

1. Generate a token

Sign in and open Settings → API Tokens
Click "New token"
Give it a name (e.g. "CI bot") and pick a role
Copy the token immediately — it is shown once

2. Authenticate a request

curl https://app.fastfollow.ai/api/contacts \
  -H "Authorization: Bearer ff_live_•••" \
  -H "Content-Type: application/json"

Tokens prefixed with ff_live_ grant full API access with the scoped role. Treat them like passwords — store in a secret manager, never commit to source control, rotate at least every 90 days.

Token lifecycle

Three token types with different TTLs and storage rules

Token	TTL	Where it lives	Purpose
Access token	15 minutes	In-memory (browser) or Authorization header (server)	Authenticate individual API requests
Refresh token	7 days, rotates on every use	httpOnly Secure cookie (browser only)	Mint new access tokens without re-authenticating
API token	Until manually revoked	You store it — never logged or echoed back from the API	Long-running automations and integrations

Role-based access control

Five roles with inherited permissions, scoped to a single tenant

owner

Full access. Can manage billing, members, and all tenant settings.

admin

Tenant administration. Manage integrations, users, and team settings — cannot change billing or transfer ownership.

sales_manager

Team-level visibility. Read all team members’ pipelines, follow-ups, and rooms.

sales_rep

Individual contributor. Read and write own pipeline, follow-ups, and rooms. Cannot access teammates’ data.

viewer

Read-only across visible data. Useful for stakeholders and observers.

Permission	owner	admin	manager	rep	viewer
contacts:read
contacts:write
followups:read
followups:write
followups:approve
rooms:read
rooms:publish
integrations:manage
users:invite
billing:manage
tenant:transfer

Tenant isolation

Every authenticated request carries a tenant ID derived from the user's session or API token. Every database query is automatically scoped to that tenant — there is no API path that allows cross-tenant reads or writes.

If you operate multiple FastFollow tenants (e.g. one per customer in a reseller model), you must generate a separate API token for each. Tokens cannot be impersonated across tenants.

JWT claims structure

{
  "sub": "usr_01H...",
  "email": "user@example.com",
  "tenantId": "ten_01H...",
  "role": "sales_manager",
  "permissions": [
    "contacts:read",
    "contacts:write",
    "followups:approve"
  ],
  "iat": 1714540800,
  "exp": 1714541700
}

Rate limits

Returned headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After

Authenticated API token

600 requests / minute, burst to 1,000

Browser session

1,200 requests / minute per user

Unauthenticated (public room access)

60 requests / minute per IP

Auth endpoints (sign-in, signup)

20 attempts / 15 minutes per IP

Exceeding the limit returns HTTP 429 with a Retry-After header indicating seconds until the window resets.

Security best practices

Recommendations for handling FastFollow tokens

Rotate API tokens every 90 days

Generate a new token, deploy it, delete the old one. FastFollow lets you keep two active tokens during the rotation window.

Use a secret manager

Store tokens in AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or 1Password — never in .env files committed to git.

Scope tokens to the narrowest role

If your CI bot only reads contacts, use a viewer-role token. Avoid creating owner-role tokens for any automation.

Monitor token usage

The audit log at /admin/health surfaces every API token used and its rolling request rate. Investigate any unexpected spikes.

Revoke immediately on compromise

If a token is exposed, revoke it from Settings → API Tokens. Revocation is instant and global.

Restrict by IP (enterprise)

Enterprise tenants can pin API tokens to specific IP CIDR ranges. Contact support to enable.

Full security and compliance overview