Credentials and scopes
Summary
A credential lets a script or an AI agent work in Talewright for one member, without that member's password or browser. There are two kinds:
- An API key: a secret string you create in the app and give to a script, an agent or an MCP client. This page is about API keys.
- A connected app: an agent such as Claude Code or Codex that you approve in the browser. See Connected apps.
Both kinds follow the same rules. A credential belongs to one member and one organization. It is limited to the workspaces and the scopes chosen when it was made, and it expires. It never has more rights than its member has at the moment of each request. Some things no credential can do at all: they need a person signed in with a browser.
Who can do what
| Action | Owner | Admin | Member | Signed-in person | Credential | Scope a credential needs |
|---|---|---|---|---|---|---|
| Create an API key for yourself | Yes | Yes | Yes | Yes | No | Browser only |
Give a key or an app files:approve | Yes | Yes | No | No | Browser only | |
| List, rotate and revoke your own keys | Yes | Yes | Yes | Yes | No | Browser only |
| Read the activity of your own key | Yes | Yes | Yes | Yes | No | Browser only |
| List every member's keys and connected apps (Key management) | Yes | Yes | No | No | Browser only | |
| Revoke any member's key or connected app | Yes | Yes | No | No | Browser only | |
| Read the activity of any member's key or app | Yes | Yes | No | No | Browser only | |
| Read what the presented credential is and reaches | No (401) | Yes | Any scope | |||
| List the workspaces a credential reaches | Yes | Yes | Yes | Yes | Yes | Any scope |
- "Owner or admin" for
files:approvemeans owner or admin in every workspace the credential lists. - A member needs no verified email to create a key.
How it works
What a credential is
- A credential acts for exactly one member. Everything it does is that member's action.
- A credential belongs to exactly one organization.
- A credential lists 1 to 20 workspaces of that organization. They must be workspaces its member reaches when it is created.
- A credential holds one or more scopes.
- A credential has an expiry date.
- A credential has a kind:
api_keyorconnected_app. - None of this can be edited later. To change the workspaces, the scopes or the expiry, create a new key and revoke the old one.
The key itself
- A key looks like
ak1_<public ID>_<secret>:ak1_, 12 characters,_, then 43 characters. 60 characters in all. - The full key is shown once, when it is created or rotated. It is never shown again, to anyone.
- Lists show only the prefix,
ak1_<public ID>. The prefix is not a secret. It stays the same when the key is rotated. - A key works at the REST API (
/v1) and at the MCP endpoint (/mcp). - Send it as
Authorization: Bearer ak1_...on every request. - Never send a browser cookie together with a key. A request to
/v1with both is refused with401 UNAUTHENTICATED, reasonAMBIGUOUS_CREDENTIALS. - Answers that carry a key are sent with
Cache-Control: no-store. - Every new key is announced to its member by a security email. This email cannot be turned off.
What a credential reaches
- Each request is checked again from scratch: is the credential live, does its member still belong to the organization, does the member still reach the workspace, what is the member's role now. Nothing is remembered between requests.
- A credential reaches only the workspaces it lists. Every other workspace
answers
404 NOT_FOUND, exactly like one that does not exist. This holds for IDs in paths, in request bodies, in cursors and in MCP resource addresses. - A credential always reaches the organization folder (the API's library) of its organization with its file scopes, whatever workspaces it is limited to. The organization folder is the shared root every member can open, so it is not on the credential's workspace list and cannot be left out. This is on purpose. To keep files from members and their credentials, owners and admins put them in a workspace that only they are invited to.
- A credential reaches no other organization, even when its member belongs to several.
- Answers that span workspaces show only the credential's workspaces. The organization's workspace list and a file's duplicates leave the others out.
- Counts are not cut down. Each workspace and the organization folder have
their own statuses and fields, and a status's
fileCountandpublicFileCount, the list'snoStatusFileCountand thefileCountof every field and choice count only that workspace's or organization folder's files, the same for a credential as for a person. OnlytrashedFileCountisnullfor a credential. See Statuses. - The member's role still decides. A member's key cannot change organization folder files, because a member cannot.
Scopes
There are four scopes. There is no wildcard scope and no "all" scope.
| Scope | Allows | Does not allow |
|---|---|---|
workspace:read | Reading the organization and its workspaces, the organization's members and each listed workspace's members. | Anything about files. |
files:read | Reading files, folders, tags, versions, uploads, library proposals, statuses and fields. Getting temporary URLs to download bytes, thumbnails and previews. Downloading ZIPs. Counting files by status and listing duplicate groups. Managing the member's own favorites and hiding duplicate warnings for the member. | Changing anything else. |
files:write | Everything files:read allows. Starting, completing and cancelling uploads. Renaming, moving, tagging and describing files. Setting field values. Creating, renaming, moving, trashing and restoring folders. Trashing and restoring files. Renaming and deleting tags, for a credential acting for an owner or admin of that workspace or the organization folder. Creating library proposals and rejecting their items. | Setting statuses. Making files public. Deleting for good. |
files:approve | Setting or clearing the status of files. Together with files:write: a move that makes files public, and a restore that makes public a file that was not public when it went to the trash. | Reading or changing anything else, unless another scope allows it. |
files:writeincludesfiles:read. A key withfiles:writeneeds no separatefiles:read.workspace:readhas no write counterpart. Organizations, workspaces and members are changed only in a browser.- Two operations need no particular scope. Any live credential may call them:
reading itself (
credential.read) and listing the workspaces it reaches (workspaces.list). - Over MCP, a credential sees only the tools its scopes allow. See MCP.
Every operation by scope:
| Scope | Operations (capability IDs) |
|---|---|
| Any scope (2) | workspaces.list, credential.read |
workspace:read (4) | organizations.list, organizations.get, organizations.members.list, workspaces.members.list |
files:read (44) | In each of workspace. and library.: file_statuses.list, file_fields.list, files.search, files.get, files.versions.list, files.signed_url, files.read, files.archive, files.status.count, folders.list, tags.list, uploads.list, uploads.get, library_proposals.list, library_proposals.get, favorites.list, favorites.add, favorites.reorder, favorites.remove, duplicates.list, duplicates.hide, duplicates.show |
files:write (30) | In each of workspace. and library.: files.update, files.fields.set, files.trash, files.restore, folders.create, folders.update, folders.trash, folders.restore, tags.rename, tags.delete, uploads.create, uploads.complete, uploads.cancel, library_proposals.create, library_proposals.reject |
files:approve (2) | workspace.files.status.set, library.files.status.set |
That is 82 operations a credential can call. The other 90 are either open to everyone without sign-in (12) or need a person in a browser (78). The full matrix is in Roles and permissions.
files:approve
files:approveis the authority to decide what may be public. A file is public only while its status allows public use. Whoever sets statuses therefore decides which files can be public.- That is why no write scope includes it. An agent that may rename and move files must not, by that alone, be able to open them to the world.
- It must be chosen explicitly. Nothing preselects it, in the key dialog or at consent.
- Only someone whose effective role is owner or admin in every workspace
the credential lists can give it. An organization owner or admin has that
in every workspace. An organization member has it only where their
workspace role is admin or owner. Otherwise creating the key answers
403 FORBIDDEN. - Holding the scope is not enough. Each use checks the member's role at that
moment: the effective role in the workspace for workspace files, the
organization role for organization folder files. A member who was demoted
after creating the key gets
403 FORBIDDEN. - Each use also needs the member's email to be verified. Otherwise the answer
is
403 EMAIL_NOT_VERIFIED. - Without the scope, setting a status answers
403 FORBIDDENwith reasonINSUFFICIENT_SCOPEanddetails.requiredScopes["files:approve"]. - The scope is also needed, together with
files:write, when a move would make files public: moving a file with an allowing status into a public folder, or moving a folder under a public folder. Without it the answer isINSUFFICIENT_SCOPE. When the member is not an owner or admin the answer is403 FORBIDDENwith reasonMAKES_FILES_PUBLIC. - Restoring from the trash needs
files:write. A workspace member's credential restores workspace files and folders. Only an owner's or admin's credential restores organization folder ones. A file that was public when it went to the trash comes back public for any credential that may restore it. A restore that would make any other file public is refused:403 FORBIDDENwith reasonINSUFFICIENT_SCOPEwithoutfiles:approve, and with reasonMAKES_FILES_PUBLICwhen the member is not an owner or admin. See Trash and restore. files:approvedoes not include reading. A key with onlyfiles:approvecan set statuses on file IDs it is given, but cannot list or read files.- Setting a status never makes a file public by itself, unless the file sits
in a public folder. In that case the change is refused with
409 CONFLICT, reasonVISIBILITY_CHANGE, until it is repeated withconfirmVisibilityChange: true.
What no credential can do
These need a person signed in with a browser. A credential with every scope
still gets 403 FORBIDDEN with reason SESSION_REQUIRED (or
HUMAN_APPROVAL_REQUIRED for applying a proposal).
- Make a file or a folder public or restricted. General access is set in the browser by an owner or admin. No credential creates a public link.
- Delete for good. Purging a trashed file or folder, and emptying the trash. A credential can move things to the trash, where they stay restorable.
- Apply a library proposal. An agent proposes; a person applies.
- Create, rotate, revoke or list credentials. A credential can never create, extend or recover a credential, an account or access.
- Answer an app's request to connect.
- Manage accounts and sessions. Name, password, email address, sessions, sign-out, deleting the account.
- Manage organizations and workspaces. Create, rename, delete, restore, leave.
- Manage people. Roles, removing members, workspace membership, invitations.
- Manage statuses and fields. Creating, renaming, reordering and deleting the statuses, fields and choices of a workspace or the organization folder. A credential reads the lists and sets a status or a field value on files; it does not change the lists themselves.
- Export the organization.
- Read credential activity.
Expiry
- A key is created with a lifetime of 30, 90, 180 or 365 days. The default is 90 days.
- There are no keys without an expiry.
- The expiry cannot be extended. Rotating a key does not move it.
- Once expired, a key answers
401 UNAUTHENTICATEDwith reasonINVALID_TOKENat once. - An expired key stays listed for 30 days, marked "Expired" with its expiry date, and then disappears. That holds for its member's own list and for Key management alike, and for an expired connected app too.
- It cannot be rotated. It can still be revoked, from either list, which removes it from both.
Last used and last client
lastUsedAtsays when the credential last made a request. It is refreshed at most once a minute. A key that never made a request reads "Never used".lastClientsays which MCP client last connected with the credential: its name, its version and the MCP protocol version. It isnulluntil an MCP client connects.
Rotating
- Rotating gives a key a new secret. The new key is shown once.
- The prefix, the name, the workspaces, the scopes and the expiry stay the same.
- By default the old secret stops working at once.
- You can keep the old secret working for 0 to 24 hours, so a running script can be switched without a gap. The app offers "No, stop it now", "For 1 hour", "For 6 hours" and "For 24 hours".
- While an old secret still works, the key shows when it stops
(
previousSecretExpiresAt, "Old secret until ..." in the app). - Rotating again shortens every older secret that still works to the new overlap. Rotating with no overlap stops them all at once.
- An old secret never works past the key's own expiry.
- Only the key's member rotates it. Owners and admins cannot rotate another member's key; they can revoke it.
Revoking
- A revoked key answers
401 UNAUTHENTICATEDwith reasonINVALID_TOKENat once, including any old secret still in its overlap. - Revoking cannot be undone. Create a new key instead.
- A key is revoked by its member, or by an owner or admin of its organization.
- A key is revoked automatically when its member:
- leaves the organization or is removed from it (that organization's credentials only),
- resets their password from an emailed link,
- changes their password in the app,
- sets a new password while verifying their email in another browser,
- deletes their account.
- A revoked key leaves every list. What was done with it stays readable as its activity.
When the member's access changes
| What happens to the member | What happens to the credential |
|---|---|
| Removed from one of the listed workspaces | That workspace answers 404 from the next request. The other workspaces keep working. credential.read and workspaces.list no longer show it. |
| Added back to that workspace | The credential reaches it again from the next request. |
| Removed from every listed workspace | The credential stays live but reaches no workspace. It still reaches the organization folder with its file scopes. |
| Demoted from admin to member | The credential acts as a member from the next request. files:approve stops working. |
| Promoted | The credential acts with the new role from the next request. Its scopes do not grow. |
| Leaves or is removed from the organization | The credential is revoked. |
| Resets or changes their password | Every credential of the member is revoked, in every organization. |
| Deletes their account | Every credential is revoked. |
| A listed workspace is deleted | It is out of reach. If it is restored within 30 days, the credential reaches it again. |
| The organization is deleted | The credential answers 401. If the organization is restored within 30 days, the credential works again. |
| The organization is purged | The credential is gone. |
Rate limits
- One credential may make 600 requests a minute, across REST and MCP.
- All credentials of one organization together may make 3,000 requests a minute.
- Past either limit the answer is
429 RATE_LIMITEDwithRetry-After. - One client address may fail bearer authentication 100 times in 15 minutes.
After that, every bearer request from that address is refused with
429until the window ends, valid keys included. - One member may create 20 keys in 24 hours.
- See Limits.
Oversight by owners and admins
- Owners and admins of an organization see every member's API keys and connected apps in it that are not revoked. Expired ones stay listed for 30 days, marked "Expired", exactly as in the member's own list.
- For each they see the name, the prefix or the app, the member, the workspaces, the scopes, the expiry, when it was last used and its activity.
- They never see a secret.
- They can revoke any of them. The member is not asked.
- They cannot create a key for another member, rotate another member's key or change what it reaches.
- Revoking your own credential from this page counts as revoking it yourself.
In the app
Create a key
- Open Settings > Credentials. The page has the heading "Credentials". With no keys it says "No API keys yet."
- Press "Create API key". The dialog "Create API key" opens.
- "Name": where the key is used, such as a deploy script. 1 to 100 characters.
- "Organization": the organization the key works in.
- "Workspaces": tick 1 to 20. "The key reaches these and the organization folder, and only while you do." If you reach only one workspace of the organization, it is ticked for you.
- "Permissions": tick what the key needs. Nothing is ticked for you. "Write
includes read."
- "Workspace":
workspace:read. - "Files & Assets":
files:readandfiles:write. - "Set file statuses":
files:approve. It is greyed out and marked "(owner or admin only)" unless you are owner or admin in every ticked workspace.
- "Workspace":
- "Expires": "In 30 days", "In 90 days" (preselected), "In 180 days" or "In 365 days".
- Press "Create key".
- The dialog "Copy your key" opens: "This is the only time the key "{name}" is shown. Store it in a password manager or your deployment's secrets." Press "Copy key", then "Done".
Messages in the dialog:
| Message | When |
|---|---|
| "Enter a name, up to 100 characters." | The name is empty or too long. |
| "Choose an organization you belong to." | No organization is chosen. |
| "Choose 1 to 20 workspaces." | No workspace, or more than 20, is ticked. |
| "Choose at least one permission." | No permission is ticked. |
| "Choose 30, 90, 180 or 365 days." | The lifetime is not one of the four. |
| "You can create 20 keys a day. Try again {when}." | The daily limit is reached. |
| "Copied to the clipboard." | "Copy key" worked. |
| "Could not copy. Select the key and copy it." | The browser refused to copy. |
The key list
The table "Keys" has the columns "Key", "Access" and "Expires".
- "Key": the name and the prefix.
- "Access": the organization, "Workspaces:" with their names, and the scopes.
- "Expires": the expiry date, or "Expired" with the date. Below it "Last used {time}" or "Never used". While an old secret still works: "Old secret until {time}".
- Each row has "Activity", "Rotate" and "Revoke". An expired key has no "Rotate".
- "Load more" shows more keys.
Rotate a key
- Press "Rotate" on the key's row. "Rotate {name}?" asks first: "The key gets a new secret, shown once. Its permissions and expiry stay the same."
- Choose under "Keep the old secret working": "No, stop it now" (preselected), "For 1 hour", "For 6 hours" or "For 24 hours".
- Press "Rotate key". "Copy your key" shows the new key once.
Revoke a key
- Press "Revoke" on the key's row. "Revoke {name}?" asks first: "Anything using this key stops working at once. This cannot be undone."
- Press "Revoke key", or "Cancel" to keep it.
- The row disappears and "Revoked {name}" confirms.
Key management (owners and admins)
- Open the organization's settings and follow "Key management".
- The table "Credentials" lists every member's keys and connected apps, with the columns "Key", "Member", "Permissions" and "Expires". A connected app reads "Connected app from {host}" and "Connected {date and time}" under its name, one row per connection. An expired one reads "Expired {date}" in "Expires" for 30 days.
- "Activity" shows what was done with one.
- "Revoke" asks first: "{member}'s key stops working at once. They can create a new one if they still need it." For a connected app: "{member}'s connected app stops working at once. They can connect it again if they still need it." Confirm with "Revoke key".
- A member who opens the page sees "Only owners and admins of this organization see its members' API keys."
For agents
Operations
| Operation | Capability | Access |
|---|---|---|
GET /v1/credential | credential.read (MCP tool credential_read) | Any live credential |
GET /v1/workspaces | workspaces.list (MCP tool workspaces_list) | Any live credential, or a session |
GET /v1/me/api-keys | credential.api_keys.list | Browser only |
POST /v1/me/api-keys | credential.api_keys.create | Browser only |
POST /v1/me/api-keys/{keyID}/rotate | credential.api_keys.rotate | Browser only |
DELETE /v1/me/api-keys/{keyID} | credential.api_keys.revoke | Browser only |
GET /v1/organizations/{organizationID}/credentials | credential.organization.list | Browser only, owners and admins |
DELETE /v1/organizations/{organizationID}/credentials/{credentialID} | credential.organization.revoke | Browser only, owners and admins |
GET /v1/organizations/{organizationID}/credentials/{credentialID}/activity | credential.organization.activity | Browser only |
Reading the presented credential
An agent's first questions are "who am I acting for" and "what may I do".
GET /v1/credential answers both. It takes no parameters.
curl https://app.usetalewright.com/v1/credential \
-H "Authorization: Bearer $TALEWRIGHT_API_KEY"
{
"id": "0192f0a1-6f2e-7c11-9a55-2f6d0c1e7b90",
"kind": "api_key",
"name": "Deploy script",
"user": { "id": "0192e7c4-0a10-7d55-8e21-4c9b7a6d5e30", "fullName": "Ada Example" },
"organization": { "id": "0192e7c4-0b22-7e61-9f32-5dab8b7e6f41", "name": "Keystone" },
"workspaces": [
{ "id": "0192e7c4-11aa-7b02-b6f0-5d7a1c9e3f21", "name": "Keystone Main" }
],
"scopes": ["files:read"],
"expiresAt": "2027-02-12T09:12:44Z",
"client": null
}
workspaceslists only the credential's workspaces the member still reaches.clientisnullfor an API key. For a connected app it holds the app'sclientIDandname.- A browser session calling this operation gets
401 UNAUTHENTICATED.
What a key list entry holds
The key and credential lists answer { "items": [...], "nextCursor": ... },
newest first. Each item:
| Property | Meaning |
|---|---|
id | The credential's ID. |
kind | api_key or connected_app. |
name | The key's name, or the connected app's name. |
prefix | ak1_<public ID> for a key. at1_ for a connected app. |
client | null for a key. The app's clientID and name for a connected app. |
lastClient | name, version and protocolVersion of the MCP client that last connected, or null. |
user | The member: id and fullName. |
organizationID | The organization. |
workspaceIDs | The listed workspaces that still exist. |
scopes | The scopes, in a fixed order. |
createdAt, expiresAt | When it was created and when it expires. |
lastUsedAt | When it last made a request, or null. |
previousSecretExpiresAt | While a rotated-out secret still works, when it stops. Otherwise null. |
Creating and rotating answer { "apiKey": <the item above>, "token": "ak1_..." }.
token is in that one response only.
Request bodies
Create (POST /v1/me/api-keys):
| Property | Required | Value |
|---|---|---|
name | Yes | 1 to 100 characters. |
organizationID | Yes | An organization you belong to. |
workspaceIDs | Yes | 1 to 20 different workspaces of it that you reach. |
scopes | Yes | At least one of workspace:read, files:read, files:write, files:approve. Repeats are ignored. |
expiresInDays | No | 30, 90, 180 or 365. Default 90. |
Rotate (POST /v1/me/api-keys/{keyID}/rotate):
| Property | Required | Value |
|---|---|---|
overlapHours | No | 0 to 24. Default 0. |
Edge cases
- A key lists a workspace its member is later removed from. The key keeps
working elsewhere. That workspace answers
404, the same as an unknown one, so the key cannot tell the difference. - A member of three organizations creates a key in one. The key sees that one organization only, in every list.
- A key and a cookie in one request.
401 AMBIGUOUS_CREDENTIALSat/v1. At/mcpcookies are ignored and the key is used. - An OAuth access token sent to
/v1.401 INVALID_TOKEN. Connected apps' tokens work at/mcponly. - A key sent with a scheme other than
Bearer.401 INVALID_TOKEN. - A key sent to an operation that needs no sign-in. The key is ignored, valid or not, and the operation answers as for anyone.
- Rotating with a 24-hour overlap, then rotating again with none. Both older secrets stop at once.
- Rotating a key that expires in two hours with a 24-hour overlap. The old secret stops when the key expires.
- Rotating an expired key.
404 NOT_FOUND. - Revoking a key twice. The second attempt answers
404 NOT_FOUND. - A plain member of a listed workspace asks for
files:approve.403 FORBIDDEN. The app does not offer it: the checkbox is greyed out. A member whose workspace role is admin or owner in every listed workspace may tick it. - An admin of the organization picks a workspace and
files:approve. Allowed: organization owners and admins are owner or admin in every workspace. - A member who is admin of one workspace only picks that workspace and
another.
files:approveis refused, because they are not owner or admin in both. - The 21st key in a day.
429 RATE_LIMITED. The app says "You can create 20 keys a day. Try again {when}." - A name with a line break at the end. Refused with
422onname. It is not silently trimmed. - The same workspace listed twice.
422onworkspaceIDs. - An unknown scope.
422onscopes. - A password reset. Every key of the member stops, in every organization. New keys must be created afterwards.
- An unverified member with an admin key that holds
files:approve. Setting a status answers403 EMAIL_NOT_VERIFIED. The same member can set statuses in the browser. - A key with
files:writeand nofiles:approvemoves a file with an allowing status into a public folder.403 FORBIDDEN,INSUFFICIENT_SCOPE, withrequiredScopes["files:approve"]. - An owner revokes a member's key. The member is not asked. The key's row disappears from the member's list too.
- A member opens another member's key activity.
404 NOT_FOUND.
Errors
| Code | Status | details | Meaning | What to do |
|---|---|---|---|---|
UNAUTHENTICATED | 401 | null | No bearer token on GET /v1/credential, or no session on a browser-only operation. | Send the key, or sign in. |
UNAUTHENTICATED | 401 | reason: INVALID_TOKEN | The key is malformed, unknown, expired or revoked, its member left the organization, or the organization is deleted. | Create a new key. |
UNAUTHENTICATED | 401 | reason: AMBIGUOUS_CREDENTIALS | A cookie and a bearer token together. | Send one. |
FORBIDDEN | 403 | reason: SESSION_REQUIRED | A credential called a browser-only operation. | Do it in the app. |
FORBIDDEN | 403 | reason: HUMAN_APPROVAL_REQUIRED | A credential tried to apply a library proposal. | A person applies it. |
FORBIDDEN | 403 | reason: INSUFFICIENT_SCOPE, requiredScopes | The credential lacks the scope. | Use a credential that holds it. |
FORBIDDEN | 403 | reason: MAKES_FILES_PUBLIC, becomePublic | A move would make files public and the member is not an owner or admin. | Ask an owner or admin. |
FORBIDDEN | 403 | null | The member's role does not allow it; a member asked for files:approve; a member opened Key management; the request sent a foreign Origin. | Check the role. |
EMAIL_NOT_VERIFIED | 403 | null | A status change or a change that makes files public through a credential whose member has not verified their email. | Verify the email. |
NOT_FOUND | 404 | null | A workspace or organization outside the credential; a key that is unknown, another member's, already revoked or (for rotation) expired. | Check the ID. |
VALIDATION_FAILED | 422 | field | name, organizationID, workspaceIDs, scopes, expiresInDays or overlapHours breaks its rule. | Fix that field. |
RATE_LIMITED | 429 | retryAfterSeconds | Too many requests with the credential or in the organization, too many failed authentications from the address, or more than 20 keys in a day. | Wait for Retry-After. |
Limits
| Limit | Value |
|---|---|
| Key name | 1 to 100 characters |
| Organizations per key | 1 |
| Workspaces per key | 1 to 20 |
| Scopes | 4 exist; a key holds at least 1 |
| Lifetime | 30, 90 (default), 180 or 365 days |
| Rotation overlap | 0 (default) to 24 hours |
| Keys created per member | 20 in 24 hours |
| Requests per credential | 600 a minute |
| Requests per organization, all its credentials | 3,000 a minute |
| Failed bearer authentications per client address | 100 in 15 minutes |
| "Last used" precision | Refreshed at most once a minute |
| An expired key or connected app stays listed, in the member's list and in Key management | 30 days |
Questions and answers
I lost my key. Can I see it again? No. Nobody can. Rotate the key to get a new secret, or create a new key.
Can I change a key's workspaces or scopes? No. Create a new key with what you need and revoke the old one.
Can I extend a key's expiry? No. Create a new key before the old one expires.
Can I make a key that never expires? No. The longest lifetime is 365 days.
Does files:write let my agent read files?
Yes. files:write includes files:read.
Does files:write let my agent set statuses?
No. Statuses need files:approve, which no write scope includes.
Why can I not tick "Set file statuses"? You must be owner or admin in every workspace you ticked. Untick the workspaces where you are a member, or ask an owner or admin to create the key.
Can my agent make a file public?
Not directly. Only a person in a browser sets general access. An agent with
files:approve, acting for an owner or admin, can set a status that allows
public use, and can confirm a move into a public folder.
Can my agent delete files? It can move files and folders to the trash, where they stay restorable for 30 days. It cannot delete them for good.
Can a key create another key? No. Managing credentials always needs a person in a browser.
Does a key work at both REST and MCP?
Yes. The same key works at /v1 and at /mcp.
What happens to my keys when I change my password? They are all revoked, along with your connected apps. Create new ones.
What happens to my keys when I leave an organization? Your keys and connected apps in that organization are revoked. Those in other organizations keep working.
I was made admin. Do my keys get more rights?
They act with your new role at once. Their scopes and workspaces stay as they
were, so a key without files:approve still cannot set statuses.
Can an admin use my key? No. An admin sees its name, prefix, scopes and activity, and can revoke it. The secret is never shown to anyone after creation.
Can an admin create a key for me? No. Everyone creates their own keys.
How do I find out what a key can do, from the key alone?
Call GET /v1/credential, or the MCP tool credential_read.
Why does my key get 404 for a workspace I can open in the browser?
The key does not list that workspace. Create a key that does.
Why does my key get 401 although I just created it?
Check that the whole key was copied (60 characters, starting ak1_), that it
is sent as Authorization: Bearer <key>, and that no cookie is sent with it.
Does a key reach the organization folder? Yes, always, with its file scopes, whatever workspaces it is limited to, and with its member's role: members read the organization folder, owners and admins change it. To keep files from a key, keep them in a workspace the key's member is not invited to.
Is a new key announced to anyone? Its member gets a security email. Owners and admins see it in Key management.
How do I switch a running script to a new secret without downtime? Rotate with an overlap. The old secret keeps working for the hours you choose while you deploy the new one.