API reference

API keys

The workspace's API keys.

GET/api-keys

List API keys

The keys you're accountable for (for an API key or agent, its person's), or everyone's with credentials:manage.

Permission: admin

Parameters

NameTypeRequiredDescription
afterquerystringOptionalCursor: nextAfter of the previous page.
limitquerystringOptionalPage size (1-500).
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

itemsarray of objectsRequired
This page.
items[].allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
items[].alsoRevokedobject
Only in the rotate response: what the old key made, ended with it (apiKeys and agentClients revoked, webhooks turned off).
items[].createdAtstring (date-time)Required
Created.
items[].createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
items[].createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
items[].effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role and what the organization's policy lets their API keys hold; nothing once it expired.
items[].expiresAtstring (date-time) or null
When it stops working by itself; null: never.
items[].idstring (uuid)Required
Key.
items[].kindstringRequired
Kind.One of secret, publishable
items[].lastUsedAtstring (date-time) or null
Last use.
items[].lastUsedIpstring or null
The address of its last use.
items[].namestringRequired
Name.
items[].narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, when it does: role (its person's current role holds less, or they can't act in the workspace now), policy (the organization lets members' API keys hold less), expired, or resources (it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope.
items[].prefixstringRequired
First characters, to recognize it.
items[].resourcesobject
What it reaches in the workspace.
items[].resources.adAccountsstring or array of objectsRequired
all: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.
items[].scopesarray of stringsRequired
Scopes.
items[].secretstring or null
Only in the create and rotate responses.
nextAfterstring or integer or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/api-keys" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/api-keys

Create an API key

The secret is in this response only; a replay returns the key without it. 403 while the organization lets only its owners and admins create API keys (credentialPolicy.membersMayCreateApiKeys), and a scope beyond what it lets members' keys hold (membersApiKeyAccess) is 422 invalid, saying what it allows, with no missingCapability: the role allows it.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

allowedIpsarray of strings
The addresses or ranges it works from, at most 20; a request from anywhere else is refused. Without it, or empty: anywhere.
expiresAtstring (date-time) or null
When the key stops working by itself, within two years and within the organization's limit for members when it sets one. Without it the key lasts 90 days, or that limit when it's shorter; null: it never expires, where no limit applies (otherwise 422).
kindstringRequired
publishable keys only read (pk_…). secret keys (sk_…) get the scopes you send: ["read", "review"] comments and approves only, ["read", "review", "write"] edits without publishing, ["read", "review", "write", "publish"] may also publish (spend). write doesn't include review.One of secret, publishable
namestringRequired
Name.
resourcesobject
The ad accounts it works in: all, or chosen ones by ID, as list_platforms names them. Without it, the ones the caller reaches (a person every one); an ad account the caller doesn't reach, or that isn't the workspace's, is 422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of strings
Scopes; never more than the creator holds. A secret key without scopes gets read, review, write and publish: publishing spends money, so send scopes to leave it out.

Response201 Created

allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
alsoRevokedobject
Only in the rotate response: what the old key made, ended with it (apiKeys and agentClients revoked, webhooks turned off).
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role and what the organization's policy lets their API keys hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Key.
kindstringRequired
Kind.One of secret, publishable
lastUsedAtstring (date-time) or null
Last use.
lastUsedIpstring or null
The address of its last use.
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, when it does: role (its person's current role holds less, or they can't act in the workspace now), policy (the organization lets members' API keys hold less), expired, or resources (it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope.
prefixstringRequired
First characters, to recognize it.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.
scopesarray of stringsRequired
Scopes.
secretstring or null
Only in the create and rotate responses.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/api-keys" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5a7b1ff2-8b19-4bb8-b1a0-ac57fdf1dda2" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedIps": [
      "203.0.113.7"
    ],
    "expiresAt": null,
    "kind": "secret",
    "name": "Shopify sync",
    "resources": {
      "adAccounts": "all"
    },
    "scopes": [
      "read"
    ]
  }'
PATCH/api-keys/{id}

Narrow an API key

Gives the key less access: it keeps its secret and from its next request does only what scopes keeps. A scope it doesn't hold is 422: narrowing never adds access. What the key made keeps its own access; revoke the key to end that too. Your own key, or anyone's with credentials:manage (404 otherwise). A change is audited once, with the scopes before and after.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe api key's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

resourcesobject
The ad accounts it keeps, each one it reaches now (all only while it reaches every one); a wider set is 422. Without it, it keeps what it reaches.
resources.adAccountsstring or array of stringsRequired
all, or the ad accounts' IDs, as list_platforms names them.
scopesarray of stringsRequired
What it keeps: scopes it holds now or fewer, each with what it requires beside it.

Response200 OK

allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
alsoRevokedobject
Only in the rotate response: what the old key made, ended with it (apiKeys and agentClients revoked, webhooks turned off).
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role and what the organization's policy lets their API keys hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Key.
kindstringRequired
Kind.One of secret, publishable
lastUsedAtstring (date-time) or null
Last use.
lastUsedIpstring or null
The address of its last use.
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, when it does: role (its person's current role holds less, or they can't act in the workspace now), policy (the organization lets members' API keys hold less), expired, or resources (it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope.
prefixstringRequired
First characters, to recognize it.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.
scopesarray of stringsRequired
Scopes.
secretstring or null
Only in the create and rotate responses.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/api-keys/e43d77a5-09c7-4c5c-9473-91adce433a81" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 83838e29-3455-4bc6-9f29-6657a4c7dab3" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": {
      "adAccounts": "all"
    },
    "scopes": [
      "read"
    ]
  }'
DELETE/api-keys/{id}

Revoke an API key

The key's next request is refused. Your own key, or anyone's with credentials:manage (404 otherwise). A key can't revoke itself (409): revoke it with another credential.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe api key's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response204 No Content

Done; no content.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/api-keys/e43d77a5-09c7-4c5c-9473-91adce433a81" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 6ebf11f0-f94e-4858-980b-45d693f4d949"
POST/api-keys/{id}/rotate

Rotate an API key

Creates a new key with the same name, kind, scopes and expiry, and revokes the old one in the same step. What the old key made goes with it: the API keys and agent clients it created are revoked and its webhooks turned off, counted in alsoRevoked. The new secret is in this response only. A key can't rotate itself or the key that made it (409). Your own key, or anyone's with credentials:manage (404 otherwise); the new key is yours, and a scope beyond your own access is 422 capability_not_grantable.

Permission: adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe api key's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response201 Created

allowedIpsarray of strings or null
The addresses or ranges (address/length) it works from; a request from anywhere else is refused. null: anywhere.
alsoRevokedobject
Only in the rotate response: what the old key made, ended with it (apiKeys and agentClients revoked, webhooks turned off).
createdAtstring (date-time)Required
Created.
createdBystring (uuid) or null
The person accountable: the creator, or the person an agent acts for.
createdByActorobject or null
Who created it: kind (person, api_key or agent), id and name at the time; null for credentials from before this was recorded.
effectiveCapabilitiesarray of strings
What it can do now, by capability ID: its scopes within its person's current role and what the organization's policy lets their API keys hold; nothing once it expired.
expiresAtstring (date-time) or null
When it stops working by itself; null: never.
idstring (uuid)Required
Key.
kindstringRequired
Kind.One of secret, publishable
lastUsedAtstring (date-time) or null
Last use.
lastUsedIpstring or null
The address of its last use.
namestringRequired
Name.
narrowedByarray of strings
Why effectiveCapabilities holds less than scopes, when it does: role (its person's current role holds less, or they can't act in the workspace now), policy (the organization lets members' API keys hold less), expired, or resources (it reaches only some ad accounts, so nothing that spans them all: the Agent, loops, people, integrations, everyone's credentials, the audit log or the organization). Empty: it can use every scope.
prefixstringRequired
First characters, to recognize it.
resourcesobject
What it reaches in the workspace.
resources.adAccountsstring or array of objectsRequired
all: every ad account of the workspace. Otherwise the ad accounts it reaches; what's in another one is invisible to it and refused to it.
scopesarray of stringsRequired
Scopes.
secretstring or null
Only in the create and rotate responses.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 409Conflict: a stale expectedVersion (the body carries current), a duplicate, or an Idempotency-Key reused with different input.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/api-keys/e43d77a5-09c7-4c5c-9473-91adce433a81/rotate" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 437149d5-4d6d-4e00-8000-cc7cd79d593f"