---
title: "Authentication"
description: "API key management, license validation, and OAuth flows for ComplyForm."
---

import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';

## API Key Lifecycle

### Activation

An API key is provisioned when you activate your license:

```bash
complyform activate
```

The CLI prompts for your license key, validates it against the server, and stores the resulting API key locally. See [`complyform activate`](../../cli-reference/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.

<Aside type="caution">
  Rotation is immediate and irreversible. All existing integrations using the old key will fail with `401` until updated.
</Aside>

### 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

```json
{
  "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.

<Aside type="tip">
  Run `complyform activate` periodically in environments with intermittent connectivity to keep the cache fresh.
</Aside>

## 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

<Aside type="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.
</Aside>

## License Resend

### Endpoint

```
POST /v1/license/resend
```

### Request Body

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

### Response

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

```json
{
  "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-reference/activate/) — CLI activation command
