> ## 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. Access is constrained to the organization attached to that key.
</Warning>

## Endpoint summary

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

## Required scopes

Every Organizations API endpoint requires a secret key, and each endpoint also requires one explicit scope:

* `POST /v1/organizations` -> `organizations:create`
* `GET /v1/organizations/:organizationId` -> `organizations:read`
* `PATCH /v1/organizations/:organizationId` -> `organizations:update`
* `GET /v1/organizations/:organizationId/api-keys` -> `api_keys:read`
* `POST /v1/organizations/:organizationId/api-keys` -> `api_keys:manage`
* `PATCH /v1/organizations/:organizationId/api-keys/:keyId` -> `api_keys:manage`
* `DELETE /v1/organizations/:organizationId/api-keys/:keyId` -> `api_keys:manage`
* `POST /v1/organizations/:organizationId/api-keys/:keyId/rotations` -> `api_keys:manage`

Supported secret-key scopes are:

* `*` for all current and future secret-key scopes
* `sessions:list`
* `sessions:read`
* `fingerprints:list`
* `fingerprints:read`
* `organizations:create`
* `organizations:read`
* `organizations:update`
* `api_keys:read`
* `api_keys:manage`
* `webhooks:read`
* `webhooks:manage`
* `gate:agent_tokens:verify`
* `gate:agent_tokens:revoke`
* `gate:login_sessions:consume`
* `gate:services:read`
* `gate:services:manage`

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

## `POST /v1/organizations`

Create an organization.

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

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

Retrieve organization details as `{ "data": { ... }, "meta": { ... } }`, including `status`, `created_at`, and `updated_at`.

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

Update organization fields.

Allowed status values:

* `active`
* `suspended`
* `deleted`

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

Create a publishable or secret key for an organization. Secret keys are only fully revealed once at creation time inside `data.revealed_key`.

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:

* `name`
* `type`
* `environment`
* `allowed_origins` for publishable keys
* `scopes` for secret keys

`name` is required and must be a non-empty string.

Organization-level rate limits are managed internally and cannot be set through this API.

Secret key creation requires a non-empty `scopes` list. For the recommended narrow preset, send `["sessions:read", "sessions:update", "fingerprints:read"]`. To grant all current and future scopes, set `scopes` to `["*"]`.

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

List keys for an organization. Responses use `{ "data": [...], "pagination": { ... }, "meta": { ... } }`. Each item includes:

* `id`
* `object`
* `type`
* `name`
* `environment`
* `key_preview`
* `display_key`
* `allowed_origins`
* `scopes`
* `rate_limit`
* `status`
* `created_at`
* `rotated_at`
* `revoked_at`
* `grace_expires_at`

`id` is the API key resource identifier in `key_...` format. It is not the actual `pk_...` or `sk_...` value.

`rate_limit` is retained for compatibility with older clients. Runtime enforcement uses the organization's publishable-key or secret-key bucket.

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

Update API key metadata.

Allowed fields:

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

Key type, environment, and key material are immutable. Rotate a key to change the actual credential value.

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

Revokes a key and returns the revoked API key resource inside the normal response envelope.

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`. The new full key is only returned in that rotation response under `revealed_key`.

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