> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-locadex-parallel-t9n-main-ydzk9zxoc20klj1uk5u1gd5b.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API

> API reference for Firecrawl partners to create and manage API keys for their users

## Overview

The Firecrawl Partner Integration API lets your platform create and manage Firecrawl API keys for your users directly from your own backend. Users start using Firecrawl without leaving your platform.

<Note>
  Set up the Partner API yourself in the [Firecrawl dashboard](https://www.firecrawl.dev/app/partner-api). Any admin or member of an organization can create an integration: name it, choose a setup, accept the agreement for that setup, and copy the partner key. The key is shown once. You can mint and revoke keys later under Settings. No application or approval is needed.
</Note>

There are two setups. Both provision accounts the same way through the endpoints below; they differ in who pays for the user's usage:

* **Partner API**: each provisioned account keeps its own Firecrawl plan and billing. Users start on the Free plan and upgrade with Firecrawl directly.
* **Gateway**: accounts your integration creates are enrolled in Gateway, so their eligible usage bills to your organization once the user's own credits are used. Gateway accounts are API-only and have no dashboard login of their own.

You choose the setup when you create the integration. It is not easy to change afterwards, so we recommend reviewing both options carefully before you accept the agreement. See the [Partner API page](https://www.firecrawl.dev/partner-program) for an overview.

Some partner offers include promotional credits for provisioned users; when they do, [Partner Credits](/partner-credits) describes what the user receives.

## Base URL

```
https://integrations.firecrawl.dev
```

## Authentication

All Partner Integration API requests require an `Authorization` header with your partner key:

```bash theme={null}
Authorization: Bearer <partner key>
```

Partner keys are distinct from standard Firecrawl API keys. You create and revoke them under Settings > Partner API in the [Firecrawl dashboard](https://www.firecrawl.dev/app/partner-api).

## Security Requirements

* **Server-side only**: Partner keys must only be used in server-side code. Never expose a partner key in frontend code, client-side JavaScript, or mobile applications.
* **Terms of Service**: Before calling `POST /partner/v1/accounts`, your platform must prompt the user to accept Firecrawl's [Terms of Service](https://www.firecrawl.dev/terms-of-service).

***

## Endpoints

### Create user

Provisions a Firecrawl account for one of your users, identified by email, and returns its API key.

```
POST /partner/v1/accounts
```

#### Behavior

With the **Partner API** setup:

* If the user does not yet have a Firecrawl account, a new user and team are created.
* If the user already has a Firecrawl account but no team associated with your integration, a new partner-associated team is created.
* If the user already has a Firecrawl account and a team associated with your integration, the existing team is returned.

With the **Gateway** setup:

* Every account is created for your integration alone. A request never attaches to an existing Firecrawl account, even when the email matches one. The email is stored as the account's contact address and is not used to look accounts up.
* Repeated calls for the same email return the same account and its API key.

If your integration includes promotional credits, they are applied once, when the account is first created.

#### Request

```bash cURL theme={null}
curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

**Body**

| Field   | Type   | Required | Description                                                                                     |
| ------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `email` | string | Yes      | The user's email address. With the Gateway setup it is stored as the account's contact address. |

#### Response

**`200 OK`**

```json theme={null}
{
  "apiKey": "fc-...",
  "alreadyExisted": false
}
```

With the Gateway setup the response also carries the enrollment status:

```json theme={null}
{
  "apiKey": "fc-...",
  "alreadyExisted": false,
  "gatewayStatus": "enrolled"
}
```

| Field            | Type    | Description                                                                                                                                          |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`         | string  | The Firecrawl API key for this user's partner-associated team                                                                                        |
| `alreadyExisted` | boolean | `true` if your integration had already provisioned an account for this email. It says nothing about whether the email exists elsewhere in Firecrawl. |
| `gatewayStatus`  | string  | Gateway integrations only. `enrolled` on the call that creates the account, `already_enrolled` on repeated calls for the same email.                 |

#### Errors

| Status | Description                                                     |
| ------ | --------------------------------------------------------------- |
| `400`  | Bad request - `email` is missing or malformed                   |
| `401`  | Unauthorized - the partner key is incorrect or invalid          |
| `500`  | Internal server error - these errors are monitored by Firecrawl |

***

### Validate API Key

Validates a Firecrawl API key and returns the associated team name and user email address. The API key will only return as valid if it was created through this partner integration.

```
POST /partner/v1/api-keys/validate
```

#### Important Notes

* Firecrawl API keys do not have permissions or an expiry date.
* API keys can be manually deleted by users at any time.
* Deleted API keys are not soft-deleted. Firecrawl cannot distinguish a deleted key from one that never existed.

#### Request

```bash cURL theme={null}
curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/validate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'
```

**Body**

| Field    | Type   | Required | Description             |
| -------- | ------ | -------- | ----------------------- |
| `apiKey` | string | Yes      | The API key to validate |

#### Response

**`200 OK`**

```json theme={null}
{
  "teamName": "Example Team",
  "email": "user@example.com"
}
```

| Field      | Type   | Description                                                                                                |
| ---------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `teamName` | string | The name of the team associated with this API key                                                          |
| `email`    | string | The email the account was provisioned with. For Gateway accounts this is the contact address you supplied. |

#### Errors

| Status | Description                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `400`  | Bad request - the API key is malformed                                                                |
| `401`  | Unauthorized - the partner key is incorrect or invalid                                                |
| `404`  | API key not identifiable - the key does not exist or was not created through this partner integration |
| `500`  | Internal server error - these errors are monitored by Firecrawl                                       |

***

### Rotate API Key

Deletes an existing Firecrawl API key and creates a new one for the same user and team.

```
POST /partner/v1/api-keys/rotate
```

#### Request

```bash cURL theme={null}
curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/rotate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'
```

**Body**

| Field    | Type   | Required | Description                       |
| -------- | ------ | -------- | --------------------------------- |
| `apiKey` | string | Yes      | The API key to delete and replace |

#### Response

**`200 OK`**

```json theme={null}
{
  "apiKey": "fc-..."
}
```

| Field    | Type   | Description               |
| -------- | ------ | ------------------------- |
| `apiKey` | string | The newly created API key |

#### Errors

| Status | Description                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------- |
| `401`  | Unauthorized - the partner key is incorrect or invalid                                                |
| `404`  | API key not identifiable - the key does not exist or was not created through this partner integration |
| `500`  | Internal server error - these errors are monitored by Firecrawl                                       |

***

## Get Started

Create your integration in the [Firecrawl dashboard](https://www.firecrawl.dev/app/partner-api): sign in, choose Partner API or Gateway, accept the agreement, and copy your partner key. The setup is not easy to change afterwards, so please confirm your choice before accepting the agreement. Then call the endpoints above from your server. Questions about your setup? Write to [help@firecrawl.com](mailto:help@firecrawl.com). A larger integration in mind? Write to [partnerships@firecrawl.dev](mailto:partnerships@firecrawl.dev).