---
title: "API Reference"
description: "ComplyForm REST API for programmatic access to dashboard, licensing, and drift features."
---

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

All API requests target the base URL:

```
https://api.complyform.dev
```

## Authentication

ComplyForm uses three authentication methods depending on the endpoint.

<Tabs>
  <TabItem label="API Key (Team+)">
    Pass your API key in the `X-API-Key` header:

    ```bash
    curl -H "X-API-Key: cf_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
      https://api.complyform.dev/v1/dashboard/push
    ```

    API keys are provisioned during [`complyform activate`](../../cli-reference/activate/) and grant access to:

    - [Dashboard push](../dashboard-push/) — upload scan results
    - Project management — create, list, archive projects
    - Exports — CSV and JSON report downloads
    - Drift configuration — set baseline and alert thresholds

    See [Authentication](../authentication/) for key rotation and storage guidance.
  </TabItem>
  <TabItem label="License Key Hash">
    Pass the SHA-256 hash of your license key in the `X-License-Key-Hash` header:

    ```bash
    curl -H "X-License-Key-Hash: sha256_of_license_key" \
      https://api.complyform.dev/v1/license/validate
    ```

    Used for:

    - License validation — confirm tier, features, and expiry
    - Profile bundle checks — verify latest compliance profile version

    The CLI computes this hash automatically. You never send the raw license key over the wire.
  </TabItem>
  <TabItem label="OAuth (Dashboard)">
    Browser-based dashboard authentication uses Google Sign-In or SAML SSO. After successful login, the server issues an encrypted session cookie.

    - Google OAuth — available on all tiers
    - SAML SSO — Enterprise tier, enforced when configured by your IdP admin

    OAuth is not used for API calls from the CLI or CI/CD. See [Authentication](../authentication/) for the full OAuth flow.
  </TabItem>
</Tabs>

## Rate Limits

All endpoints enforce rate limits per source IP or API key. Exceeding a limit returns `429 Too Many Requests` or, for abuse-prone endpoints, a temporary ban.

| Endpoint Category   | Limit       | Exceeded Behavior       |
| ------------------- | ----------- | ----------------------- |
| Auth (login)        | 10 / min    | 5-minute ban            |
| License validation  | 10 / min    | `429` response          |
| Drift ingestion     | 120 / min   | `429` response          |
| License resend      | 3 / min     | 15-minute ban           |
| Dashboard writes    | 5 / min     | `429` response          |
| Export              | 10 / min    | `429` response          |
| General             | 60 / min    | `429` response          |

<Aside type="caution">
  Ban durations are cumulative. Repeated violations within a ban window extend the lockout.
</Aside>

## Response Format

All responses are JSON. Successful requests return a top-level object with endpoint-specific fields. Errors include `error` and `message`:

```json
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Retry after 60 seconds."
}
```

Common HTTP status codes:

| Code  | Meaning                                      |
| ----- | -------------------------------------------- |
| `200` | Success                                      |
| `400` | Malformed request body or missing fields      |
| `401` | Missing or invalid authentication             |
| `403` | Valid credentials but insufficient tier/scope  |
| `409` | Conflict (e.g., duplicate project label)       |
| `429` | Rate limit exceeded                           |
| `500` | Internal server error                         |

## CORS

The API sets `Access-Control-Allow-Origin` to:

- `https://dashboard.complyform.dev`
- `https://complyform.dev`

CLI and CI/CD integrations are not affected by CORS since they make server-to-server requests.

## Endpoints

| Endpoint                             | Method | Auth           | Description                              |
| ------------------------------------ | ------ | -------------- | ---------------------------------------- |
| [`/v1/dashboard/push`](../dashboard-push/) | `POST` | API Key        | Push scan results to the dashboard       |
| `/v1/license/validate`               | `POST` | License Hash   | Validate license and fetch profile bundle |
| `/v1/license/resend`                 | `POST` | None           | Resend license key to registered email    |
| `/v1/drift/ingest`                   | `POST` | API Key        | Submit drift detection events             |

See [Authentication](../authentication/) for details on each auth method, key lifecycle, and the OAuth flow.
