> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Organizations API

> Manage Foil organizations and API keys over REST: create organizations, provision publishable and secret keys, set scopes, and rotate or revoke keys.

The Organizations API is intended for admin and provisioning workflows. It is not required for a standard browser integration.

> [!WARNING]
>
> All Organizations endpoints require a secret key. Every `/v1/organizations/:organizationId` endpoint works only for the organization that owns the key. A request that names any other organization returns `403` with `auth.organization_access_denied`.

`POST /v1/organizations` creates a separate organization, but it doesn't give the calling key access to that organization. To manage the new organization's API keys, use a secret key that belongs to the new organization.

## Endpoint summary

| Method | Path | Purpose | Required scope |
| - | - | - | - |
| `POST` | `/v1/organizations` | Create an organization | `organizations:create` |
| `GET` | `/v1/organizations/:organizationId` | Retrieve organization details | `organizations:read` |
| `PATCH` | `/v1/organizations/:organizationId` | Update organization name or status | `organizations:update` |
| `POST` | `/v1/organizations/:organizationId/api-keys` | Create a publishable or secret key | `api_keys:manage` |
| `GET` | `/v1/organizations/:organizationId/api-keys` | List API keys for an organization | `api_keys:read` |
| `PATCH` | `/v1/organizations/:organizationId/api-keys/:keyId` | Rename a key or update origins/scopes | `api_keys:manage` |
| `DELETE` | `/v1/organizations/:organizationId/api-keys/:keyId` | Revoke a key | `api_keys:manage` |
| `POST` | `/v1/organizations/:organizationId/api-keys/:keyId/rotations` | Rotate a key | `api_keys:manage` |

A request whose key lacks the required scope returns `403` with `auth.insufficient_scope`.

A key can grant only the scopes it holds. Creating or updating a secret key with a scope the calling key doesn't hold returns `403` with `auth.insufficient_scope`, and so does rotating or editing a key that holds such a scope, because the rotation response reveals a replacement with the same scopes. A key with only `api_keys:manage` therefore can't mint a `*` key or widen itself. Revoking a key isn't limited this way.

A test secret key (`sk_test_*`) can create, change, rotate, and revoke only test keys. A request from a test key that would create or change a live key returns `403` with `auth.live_key_required`. Use a live secret key to manage live keys.

`PATCH /v1/organizations/:organizationId` also needs a live secret key. A test key gets `403` with `auth.live_key_required`. A test key can still retrieve the organization.

## Secret-key scopes

A secret key carries a list of scopes, and each endpoint requires one. The scopes are:

| Scope | Grants |
| - | - |
| `*` | All current and future secret-key scopes. |
| `sessions:list` | List sessions. |
| `sessions:read` | Read the detail of one session. |
| `sessions:update` | Attach or clear your own `client_user_id` and `client_application_id` on a session. |
| `fingerprints:list` | List visitor fingerprints. |
| `fingerprints:read` | Read the detail of one visitor fingerprint. |
| `agents:ip_rotation` | Check whether an agent should rotate its current proxy IP. |
| `organizations:create` | Create organizations. |
| `organizations:read` | Read organization details. |
| `organizations:update` | Update the organization name and status. |
| `api_keys:read` | List API keys. |
| `api_keys:manage` | Create, update, rotate, and revoke API keys. |
| `webhooks:read` | Read webhook endpoints, subscriptions, and event history. |
| `webhooks:manage` | Create, update, disable, test, and rotate the secret of webhook endpoints. |

Older secret keys that still carry the removed `organizations:manage` scope must be rotated or recreated before they can use organization-management endpoints.

See [Authentication](https://usefoil.com/docs/api-reference/authentication.md#scopes) for the endpoint-to-scope table across the whole API.

## `POST /v1/organizations`

Create an organization. Requires a secret key with the `organizations:create` scope.

```json theme={"dark"}
{
  "name": "Foil Production",
  "slug": "foil-production"
}
```

`name` must be a non-empty string. `slug` must contain only lowercase letters, digits, and hyphens. A slug that another organization already uses returns `409` with `request.conflict`. A successful request returns `201` with the organization resource.

## `GET /v1/organizations/:organizationId`

Retrieve organization details as `{ "data": { ... }, "meta": { ... } }`, including `status`, `created_at`, and `updated_at`. Requires a secret key with the `organizations:read` scope.

## `PATCH /v1/organizations/:organizationId`

Update organization fields. Requires a live secret key (`sk_live_*`) with the `organizations:update` scope. A test key returns `403` with `auth.live_key_required`.

Send `name` (a non-empty string), `status`, or both. Allowed status values:

* `active`
* `suspended`

> [!WARNING]
>
> A `suspended` organization rejects every request from its own keys with `403` and `auth.organization_inactive`. That includes the key that made the change, so you can't set the status back to `active` through the API.

To delete an organization and its data, email [support@usefoil.com](mailto:support@usefoil.com) from an owner's address. The API doesn't delete organizations.

## `POST /v1/organizations/:organizationId/api-keys`

Create a publishable or secret key for an organization. Requires a secret key with the `api_keys:manage` scope.

The response is `201` with the API key resource. The full key appears in `data.revealed_key` in this response. For a secret key, this is the only time Foil returns the full value, so store it before you discard the response. Publishable keys are public by design, so their resource also carries the full value as `display_key` on later reads.

The API key resource `id` uses the `key_...` format. This is the identifier you should persist for future revoke and rotate calls.

Customer-managed requests can set these fields:

| Field | Type | Notes |
| - | - | - |
| `name` | string | Required. Must be a non-empty string. |
| `type` | `"publishable"` or `"secret"` | Defaults to `publishable`. |
| `environment` | `"test"` or `"live"` | Defaults to `test`. |
| `client_target` | `"browser"`, `"native-ios"`, or `"native-android"` | Publishable keys only. Defaults to `browser`. A native key works only with the matching Foil mobile SDK, and it can't have `allowed_origins`. |
| `allowed_origins` | array of strings | Browser publishable keys only. See [Origin rules](#origin-rules). An empty list or an omitted field means the key accepts any origin. |
| `scopes` | array of strings | Required for secret keys. Must be a non-empty list of supported scopes, and isn't allowed on publishable keys. |

Foil manages rate limits itself, so a request that includes `rate_limit` returns `422` with the field error `rate_limit: not_allowed`. See [Rate limits](https://usefoil.com/docs/api-reference/rate-limits.md).

Secret key creation requires a non-empty `scopes` list. For the recommended narrow preset, send `["sessions:read", "sessions:update", "fingerprints:read"]`. This preset can't list sessions or fingerprints, so add `sessions:list` or `fingerprints:list` if your integration needs those endpoints. To grant all current and future scopes, set `scopes` to `["*"]`.

```bash theme={"dark"}
curl https://api.usefoil.com/v1/organizations/org_.../api-keys \
  -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "type": "secret",
    "environment": "live",
    "scopes": ["sessions:read", "sessions:update", "fingerprints:read"]
  }'
```

Invalid values return `422` with `request.validation_failed` and a `details.fields` entry that names the field.

### Origin rules

Each entry in `allowed_origins` is one of these:

| Entry | Matches |
| - | - |
| `https://app.example.com` | Exactly that origin. Use the scheme and host only, with no path and no port. |
| `https://*.example.com` | `example.com` and any of its subdomains over HTTPS. The wildcard needs a domain of at least two labels after `*.`, so `https://*.com` is rejected. |
| `*` | Any origin. |

Test keys also accept an exact `http` or `https` origin with any host and port, such as `http://localhost:3000`, so you can develop against a local server or a device on your network.

A request from an origin that the list doesn't match, or a request without an `Origin` header, returns `403` with `auth.origin_not_allowed`.

## `GET /v1/organizations/:organizationId/api-keys`

List keys for an organization. Requires a secret key with the `api_keys:read` scope. Responses use `{ "data": [...], "pagination": { ... }, "meta": { ... } }`. Keys are ordered newest first and include revoked keys. The endpoint accepts `limit` and `cursor`. See [Pagination](https://usefoil.com/docs/api-reference/pagination.md). Each item includes:

| Field | Meaning |
| - | - |
| `id` | The API key resource identifier in `key_...` format. It is not the actual `pk_...` or `sk_...` value. |
| `object` | Always `api_key`. |
| `type` | `publishable` or `secret`. |
| `name` | The key's name. |
| `environment` | `test` or `live`. |
| `status` | `active`, `rotating`, or `revoked`. |
| `key_preview` | A masked preview of the key. |
| `display_key` | The full key value. Present only for publishable keys. |
| `allowed_origins` | The allowed origins, or `null` when the key accepts any origin. |
| `client_target` | `browser`, `native-ios`, or `native-android` for publishable keys, and `null` for secret keys. |
| `scopes` | The scopes of a secret key, and `null` for publishable keys. |
| `rate_limit` | Retained for compatibility with older clients. Runtime enforcement uses the organization's publishable-key or secret-key bucket. |
| `last_used_at` | When the key last authenticated a request, or `null` if it has never been used. |
| `created_at` | When Foil created the key. |
| `rotated_at` | When the key was rotated, or `null`. |
| `revoked_at` | When the key was revoked, or `null`. |
| `grace_expires_at` | For a `rotating` key, when it stops working. Otherwise `null`. |

## `PATCH /v1/organizations/:organizationId/api-keys/:keyId`

Update API key metadata. Requires a secret key with the `api_keys:manage` scope.

Allowed fields:

* `name` for publishable and secret keys
* `allowed_origins` for publishable keys
* `scopes` for secret keys

Send at least one field. Sending `allowed_origins` for a secret key, `scopes` for a publishable key, or `rate_limit` returns `422`. A revoked key returns `404`.

Key type, environment, client target, and key material are immutable. Rotate a key to change the actual credential value. Changes to scopes and allowed origins take up to about 15 seconds to apply. See [Authentication](https://usefoil.com/docs/api-reference/authentication.md#revoking-a-key).

## `DELETE /v1/organizations/:organizationId/api-keys/:keyId`

Revokes a key and returns the revoked API key resource inside the normal response envelope, with status `200`. Requires a secret key with the `api_keys:manage` scope. Revoking a key that is already revoked returns the same `200` response, so you can retry a revoke whose response you didn't receive.

Pass the API key resource `id` here, not the `pk_...` key value.

## `POST /v1/organizations/:organizationId/api-keys/:keyId/rotations`

Rotates a key and returns the replacement key in `data`, with status `201`. Requires a secret key with the `api_keys:manage` scope. The new full key is only returned in that rotation response under `revealed_key`.

The replacement has the same type, environment, name, origins, client target, and scopes. The old key stays valid for 24 hours. During that time its status is `rotating` and its `grace_expires_at` shows when it stops working. See [Authentication](https://usefoil.com/docs/api-reference/authentication.md#rotating-a-key).

A key that is already `rotating` can't be rotated again, and the request returns `409` with `request.conflict`. During its grace period the old key can still read data and authenticate collection, but it can't create, change, rotate, or revoke keys, create or update organizations, or change webhook endpoints. Those requests return `403` with `auth.insufficient_scope`. To end the grace period early, revoke the old key.

Pass the API key resource `id` here, not the actual `pk_...` or `sk_...` key value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.