API keys
The workspace's 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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
after | string | Optional | Cursor: nextAfter of the previous page. |
limit | string | Optional | Page size (1-500). |
Pluto-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
items- This page.
items[].allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. items[].alsoRevoked- Only in the rotate response: what the old key made, ended with it (
apiKeysandagentClientsrevoked,webhooksturned off). items[].createdAt- Created.
items[].createdBy- The person accountable: the creator, or the person an agent acts for.
items[].createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. items[].effectiveCapabilities- 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[].expiresAt- When it stops working by itself; null: never.
items[].id- Key.
items[].kind- Kind.One of
secret,publishable items[].lastUsedAt- Last use.
items[].lastUsedIp- The address of its last use.
items[].name- Name.
items[].narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, 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, orresources(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[].prefix- First characters, to recognize it.
items[].resources- What it reaches in the workspace.
items[].resources.adAccountsall: 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[].scopes- Scopes.
items[].secret- Only in the create and rotate responses.
nextAfter- Cursor for the next page; null at the end.
curl "$PLUTO_API/api-keys" \
-H "Authorization: Bearer $PLUTO_KEY"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
allowedIps- The addresses or ranges it works from, at most 20; a request from anywhere else is refused. Without it, or empty: anywhere.
expiresAt- 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 (otherwise422). kindpublishablekeys only read (pk_…).secretkeys (sk_…) get thescopesyou send:["read", "review"]comments and approves only,["read", "review", "write"]edits without publishing,["read", "review", "write", "publish"]may also publish (spend).writedoesn't includereview.One ofsecret,publishablename- Name.
resources- 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, is422. Chosen ones leave out what spans every ad account: the Agent, loops, people, integrations, everyone's credentials, the audit log and the organization. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- Scopes; never more than the creator holds. A
secretkey withoutscopesgets read, review, write and publish: publishing spends money, so sendscopesto leave it out.
Response
allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. alsoRevoked- Only in the rotate response: what the old key made, ended with it (
apiKeysandagentClientsrevoked,webhooksturned off). createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- 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.
expiresAt- When it stops working by itself; null: never.
id- Key.
kind- Kind.One of
secret,publishable lastUsedAt- Last use.
lastUsedIp- The address of its last use.
name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, 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, orresources(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. prefix- First characters, to recognize it.
resources- What it reaches in the workspace.
resources.adAccountsall: 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.scopes- Scopes.
secret- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
]
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The api key's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The 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
resources- The ad accounts it keeps, each one it reaches now (
allonly while it reaches every one); a wider set is422. Without it, it keeps what it reaches. resources.adAccountsall, or the ad accounts' IDs, as list_platforms names them.scopes- What it keeps: scopes it holds now or fewer, each with what it requires beside it.
Response
allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. alsoRevoked- Only in the rotate response: what the old key made, ended with it (
apiKeysandagentClientsrevoked,webhooksturned off). createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- 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.
expiresAt- When it stops working by itself; null: never.
id- Key.
kind- Kind.One of
secret,publishable lastUsedAt- Last use.
lastUsedIp- The address of its last use.
name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, 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, orresources(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. prefix- First characters, to recognize it.
resources- What it reaches in the workspace.
resources.adAccountsall: 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.scopes- Scopes.
secret- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"
]
}'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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The api key's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The api key's ID. |
Idempotency-Key | string | Optional | The 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-Workspace | string (uuid) | Optional | The workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403. |
Response
allowedIps- The addresses or ranges (
address/length) it works from; a request from anywhere else is refused. null: anywhere. alsoRevoked- Only in the rotate response: what the old key made, ended with it (
apiKeysandagentClientsrevoked,webhooksturned off). createdAt- Created.
createdBy- The person accountable: the creator, or the person an agent acts for.
createdByActor- Who created it:
kind(person, api_key or agent),idandnameat the time; null for credentials from before this was recorded. effectiveCapabilities- 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.
expiresAt- When it stops working by itself; null: never.
id- Key.
kind- Kind.One of
secret,publishable lastUsedAt- Last use.
lastUsedIp- The address of its last use.
name- Name.
narrowedBy- Why
effectiveCapabilitiesholds less thanscopes, 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, orresources(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. prefix- First characters, to recognize it.
resources- What it reaches in the workspace.
resources.adAccountsall: 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.scopes- Scopes.
secret- 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 carriescurrent), a duplicate, or an Idempotency-Key reused with different input. - 422Validation failed;
errorslists every field problem at once. - 429Too many requests from this credential. Wait
Retry-Afterseconds. 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"