Talewright Docs Open the app

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

ActionOwnerAdminMemberSigned-in personCredentialScope a credential needs
Create an API key for yourselfYesYesYesYesNoBrowser only
Give a key or an app files:approveYesYesNoNoBrowser only
List, rotate and revoke your own keysYesYesYesYesNoBrowser only
Read the activity of your own keyYesYesYesYesNoBrowser only
List every member's keys and connected apps (Key management)YesYesNoNoBrowser only
Revoke any member's key or connected appYesYesNoNoBrowser only
Read the activity of any member's key or appYesYesNoNoBrowser only
Read what the presented credential is and reachesNo (401)YesAny scope
List the workspaces a credential reachesYesYesYesYesYesAny scope
  • "Owner or admin" for files:approve means 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_key or connected_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 /v1 with both is refused with 401 UNAUTHENTICATED, reason AMBIGUOUS_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 fileCount and publicFileCount, the list's noStatusFileCount and the fileCount of every field and choice count only that workspace's or organization folder's files, the same for a credential as for a person. Only trashedFileCount is null for 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.

ScopeAllowsDoes not allow
workspace:readReading the organization and its workspaces, the organization's members and each listed workspace's members.Anything about files.
files:readReading 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:writeEverything 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:approveSetting 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:write includes files:read. A key with files:write needs no separate files:read.
  • workspace:read has 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:

ScopeOperations (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:approve is 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 FORBIDDEN with reason INSUFFICIENT_SCOPE and details.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 is INSUFFICIENT_SCOPE. When the member is not an owner or admin the answer is 403 FORBIDDEN with reason MAKES_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 FORBIDDEN with reason INSUFFICIENT_SCOPE without files:approve, and with reason MAKES_FILES_PUBLIC when the member is not an owner or admin. See Trash and restore.
  • files:approve does not include reading. A key with only files:approve can 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, reason VISIBILITY_CHANGE, until it is repeated with confirmVisibilityChange: 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 UNAUTHENTICATED with reason INVALID_TOKEN at 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

  • lastUsedAt says 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".
  • lastClient says which MCP client last connected with the credential: its name, its version and the MCP protocol version. It is null until 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 UNAUTHENTICATED with reason INVALID_TOKEN at 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 memberWhat happens to the credential
Removed from one of the listed workspacesThat 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 workspaceThe credential reaches it again from the next request.
Removed from every listed workspaceThe credential stays live but reaches no workspace. It still reaches the organization folder with its file scopes.
Demoted from admin to memberThe credential acts as a member from the next request. files:approve stops working.
PromotedThe credential acts with the new role from the next request. Its scopes do not grow.
Leaves or is removed from the organizationThe credential is revoked.
Resets or changes their passwordEvery credential of the member is revoked, in every organization.
Deletes their accountEvery credential is revoked.
A listed workspace is deletedIt is out of reach. If it is restored within 30 days, the credential reaches it again.
The organization is deletedThe credential answers 401. If the organization is restored within 30 days, the credential works again.
The organization is purgedThe 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_LIMITED with Retry-After.
  • One client address may fail bearer authentication 100 times in 15 minutes. After that, every bearer request from that address is refused with 429 until 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

  1. Open Settings > Credentials. The page has the heading "Credentials". With no keys it says "No API keys yet."
  2. Press "Create API key". The dialog "Create API key" opens.
  3. "Name": where the key is used, such as a deploy script. 1 to 100 characters.
  4. "Organization": the organization the key works in.
  5. "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.
  6. "Permissions": tick what the key needs. Nothing is ticked for you. "Write includes read."
    • "Workspace": workspace:read.
    • "Files & Assets": files:read and files: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.
  7. "Expires": "In 30 days", "In 90 days" (preselected), "In 180 days" or "In 365 days".
  8. Press "Create key".
  9. 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:

MessageWhen
"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

  1. 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."
  2. Choose under "Keep the old secret working": "No, stop it now" (preselected), "For 1 hour", "For 6 hours" or "For 24 hours".
  3. Press "Rotate key". "Copy your key" shows the new key once.

Revoke a key

  1. Press "Revoke" on the key's row. "Revoke {name}?" asks first: "Anything using this key stops working at once. This cannot be undone."
  2. Press "Revoke key", or "Cancel" to keep it.
  3. The row disappears and "Revoked {name}" confirms.

Key management (owners and admins)

  1. Open the organization's settings and follow "Key management".
  2. 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.
  3. "Activity" shows what was done with one.
  4. "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".
  5. A member who opens the page sees "Only owners and admins of this organization see its members' API keys."

For agents

Operations

OperationCapabilityAccess
GET /v1/credentialcredential.read (MCP tool credential_read)Any live credential
GET /v1/workspacesworkspaces.list (MCP tool workspaces_list)Any live credential, or a session
GET /v1/me/api-keyscredential.api_keys.listBrowser only
POST /v1/me/api-keyscredential.api_keys.createBrowser only
POST /v1/me/api-keys/{keyID}/rotatecredential.api_keys.rotateBrowser only
DELETE /v1/me/api-keys/{keyID}credential.api_keys.revokeBrowser only
GET /v1/organizations/{organizationID}/credentialscredential.organization.listBrowser only, owners and admins
DELETE /v1/organizations/{organizationID}/credentials/{credentialID}credential.organization.revokeBrowser only, owners and admins
GET /v1/organizations/{organizationID}/credentials/{credentialID}/activitycredential.organization.activityBrowser 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
}
  • workspaces lists only the credential's workspaces the member still reaches.
  • client is null for an API key. For a connected app it holds the app's clientID and name.
  • 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:

PropertyMeaning
idThe credential's ID.
kindapi_key or connected_app.
nameThe key's name, or the connected app's name.
prefixak1_<public ID> for a key. at1_ for a connected app.
clientnull for a key. The app's clientID and name for a connected app.
lastClientname, version and protocolVersion of the MCP client that last connected, or null.
userThe member: id and fullName.
organizationIDThe organization.
workspaceIDsThe listed workspaces that still exist.
scopesThe scopes, in a fixed order.
createdAt, expiresAtWhen it was created and when it expires.
lastUsedAtWhen it last made a request, or null.
previousSecretExpiresAtWhile 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):

PropertyRequiredValue
nameYes1 to 100 characters.
organizationIDYesAn organization you belong to.
workspaceIDsYes1 to 20 different workspaces of it that you reach.
scopesYesAt least one of workspace:read, files:read, files:write, files:approve. Repeats are ignored.
expiresInDaysNo30, 90, 180 or 365. Default 90.

Rotate (POST /v1/me/api-keys/{keyID}/rotate):

PropertyRequiredValue
overlapHoursNo0 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_CREDENTIALS at /v1. At /mcp cookies are ignored and the key is used.
  • An OAuth access token sent to /v1. 401 INVALID_TOKEN. Connected apps' tokens work at /mcp only.
  • 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:approve is 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 422 on name. It is not silently trimmed.
  • The same workspace listed twice. 422 on workspaceIDs.
  • An unknown scope. 422 on scopes.
  • 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 answers 403 EMAIL_NOT_VERIFIED. The same member can set statuses in the browser.
  • A key with files:write and no files:approve moves a file with an allowing status into a public folder. 403 FORBIDDEN, INSUFFICIENT_SCOPE, with requiredScopes ["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

CodeStatusdetailsMeaningWhat to do
UNAUTHENTICATED401nullNo bearer token on GET /v1/credential, or no session on a browser-only operation.Send the key, or sign in.
UNAUTHENTICATED401reason: INVALID_TOKENThe key is malformed, unknown, expired or revoked, its member left the organization, or the organization is deleted.Create a new key.
UNAUTHENTICATED401reason: AMBIGUOUS_CREDENTIALSA cookie and a bearer token together.Send one.
FORBIDDEN403reason: SESSION_REQUIREDA credential called a browser-only operation.Do it in the app.
FORBIDDEN403reason: HUMAN_APPROVAL_REQUIREDA credential tried to apply a library proposal.A person applies it.
FORBIDDEN403reason: INSUFFICIENT_SCOPE, requiredScopesThe credential lacks the scope.Use a credential that holds it.
FORBIDDEN403reason: MAKES_FILES_PUBLIC, becomePublicA move would make files public and the member is not an owner or admin.Ask an owner or admin.
FORBIDDEN403nullThe 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_VERIFIED403nullA status change or a change that makes files public through a credential whose member has not verified their email.Verify the email.
NOT_FOUND404nullA workspace or organization outside the credential; a key that is unknown, another member's, already revoked or (for rotation) expired.Check the ID.
VALIDATION_FAILED422fieldname, organizationID, workspaceIDs, scopes, expiresInDays or overlapHours breaks its rule.Fix that field.
RATE_LIMITED429retryAfterSecondsToo 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

LimitValue
Key name1 to 100 characters
Organizations per key1
Workspaces per key1 to 20
Scopes4 exist; a key holds at least 1
Lifetime30, 90 (default), 180 or 365 days
Rotation overlap0 (default) to 24 hours
Keys created per member20 in 24 hours
Requests per credential600 a minute
Requests per organization, all its credentials3,000 a minute
Failed bearer authentications per client address100 in 15 minutes
"Last used" precisionRefreshed at most once a minute
An expired key or connected app stays listed, in the member's list and in Key management30 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.