Authentication

API Key Lifecycle

Activation

An API key is provisioned when you activate your license:

complyform activate

The CLI prompts for your license key, validates it against the server, and stores the resulting API key locally. See complyform activate for full usage.

Header Format

Pass the API key in every authenticated request:

X-API-Key: cf_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

All API keys use the cf_api_ prefix. If your key does not start with this prefix, it is malformed — re-run complyform activate.

Key Rotation

Rotate your API key from the dashboard:

1. Sign in at https://dashboard.complyform.dev.
2. Navigate to Settings > API Keys.
3. Click Rotate Key. The old key is invalidated immediately.
4. Copy the new key and re-run complyform activate on each machine.

Caution

Rotation is immediate and irreversible. All existing integrations using the old key will fail with 401 until updated.

Storage Guidance

The CLI stores credentials in ~/.config/complyform/credentials.json with 0600 permissions. Do not relax these permissions.

For CI/CD, store the API key as an encrypted secret:

Platform	Secret Variable
GitHub Actions	secrets.COMPLYFORM_API_KEY
GitLab CI/CD	CI/CD variable (masked, protected)
Jenkins	Credentials store (Secret text)
CircleCI	Environment variable (restricted context)

Never commit API keys to version control. Add credentials.json to your .gitignore.

License Key Validation

Endpoint

POST /v1/license/validate

Headers

X-License-Key-Hash: sha256_of_license_key

The CLI computes the SHA-256 hash of your raw license key and sends only the hash. The raw key never leaves your machine.

Response

{
  "valid": true,
  "tier": "team",
  "features": [
    "hosted_dashboard",
    "drift_detection",
    "custom_frameworks",
    "priority_support"
  ],
  "expiry": "2027-03-23T00:00:00Z",
  "bundle_url": "https://storage.complyform.dev/profiles/v2.4.0/bundle.tar.gz",
  "bundle_checksum": "sha256:a1b2c3d4e5f6..."
}

Field	Type	Description
valid	boolean	Whether the license is active and not expired
tier	string	License tier: individual, team, agency, enterprise
features	string[]	Feature flags enabled for this tier
expiry	string	ISO 8601 expiration timestamp
bundle_url	string	URL to download the latest compliance profile bundle
bundle_checksum	string	SHA-256 checksum of the profile bundle for verification

Caching

Validation responses are cached locally for 24 hours. The CLI does not call this endpoint on every scan — only when the cache has expired or when you explicitly run complyform activate.

Offline Grace Period

If the CLI cannot reach the validation endpoint (network failure, DNS issues, API outage), it continues operating with the cached license for up to 7 days. After 7 days without a successful validation, the CLI downgrades to unlicensed mode.

Tip

Run complyform activate periodically in environments with intermittent connectivity to keep the cache fresh.

OAuth Flow (Dashboard Login)

The browser-based dashboard at https://dashboard.complyform.dev uses OAuth for authentication. This flow is not used by the CLI.

Login Sequence

1. Email-first routing — You enter your email address. The server checks whether your domain has SAML SSO configured.
2. Provider redirect:
   • If no SAML configuration exists: redirect to Google OAuth consent screen.
   • If SAML is configured: redirect to your organization’s SAML IdP (Okta, Azure AD, etc.).
3. Callback — After successful authentication, the server issues an encrypted session cookie.
4. Session — The cookie is HttpOnly, Secure, SameSite=Strict.

Session Expiry

Sessions expire after 24 hours with a sliding window. Each authenticated request extends the expiry by another 24 hours from the time of the request. If you are inactive for more than 24 hours, you must re-authenticate.

Enterprise SAML Enforcement

Danger

When an Enterprise account admin enables SAML enforcement for a domain, all users with email addresses on that domain must authenticate through the configured IdP. Google OAuth is disabled for those users, and existing Google OAuth sessions are invalidated.

License Resend

Endpoint

POST /v1/license/resend

Request Body

{
  "email": "devops@example.com"
}

Response

The endpoint always returns a success response regardless of whether the email exists:

{
  "ok": true,
  "message": "If a license exists for this email, it has been sent."
}

This behavior is intentional — it prevents email enumeration attacks. An attacker cannot determine whether a given email has a ComplyForm license by observing the response.

Rate Limit

License resend is rate limited to 3 requests per minute. Exceeding this limit results in a 15-minute ban from the endpoint. This applies per source IP.

Web Form Alternative

You can also resend your license from the web at:

https://complyform.dev/resend-license

The web form calls the same endpoint and is subject to the same rate limits.

See Also

• API Reference overview — base URL, rate limits, response format
• complyform activate — CLI activation command