Organizations API

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

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.

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` 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 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.

{
  "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 secret key with the organizations:update scope. Send name (a non-empty string), status, or both. Allowed status values:

active
suspended
deleted

A suspended or deleted 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.

`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. 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. 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 ["*"].

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

`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. 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. Pass the API key resource id here, not the actual pk_... or sk_... key value.

Get started

Detection

Agents

Webhooks

Management

Organizations API

Endpoint summary

Secret-key scopes

`POST /v1/organizations`

`GET /v1/organizations/:organizationId`

`PATCH /v1/organizations/:organizationId`

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

Origin rules

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

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

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

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

​Endpoint summary

​Secret-key scopes

​POST /v1/organizations

​GET /v1/organizations/:organizationId

​PATCH /v1/organizations/:organizationId

​POST /v1/organizations/:organizationId/api-keys

​Origin rules

​GET /v1/organizations/:organizationId/api-keys

​PATCH /v1/organizations/:organizationId/api-keys/:keyId

​DELETE /v1/organizations/:organizationId/api-keys/:keyId

​POST /v1/organizations/:organizationId/api-keys/:keyId/rotations

Endpoint summary

Secret-key scopes

`POST /v1/organizations`

`GET /v1/organizations/:organizationId`

`PATCH /v1/organizations/:organizationId`

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

Origin rules

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

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

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

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