# API keys: questions and answers

Questions about Talewright API keys: creating them, scopes, workspaces,
`files:approve`, expiry, rotating, revoking, what a key can never do and how
owners and admins oversee them. The rules are in
[Credentials and scopes](../agents/credentials.md).

## The basics

### What is an API key in Talewright?

An API key is a secret string that lets a script, an AI agent or an MCP
client work in Talewright for one member, without that member's password or
browser. It is limited to the workspaces and scopes chosen when it was
created, and it expires.

More: [Credentials and scopes, Summary](../agents/credentials.md#summary)

### What is the difference between a credential and an API key?

An API key is one of the two kinds of credential. The other kind is a
connected app, which is approved in the browser. Both follow the same rules
for workspaces, scopes and expiry.

More: [Credentials and scopes, Summary](../agents/credentials.md#summary)

### Who does an API key act for?

Exactly one member: the person who created it. Everything the key does is
that member's action.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### Is an API key a service account?

No. Talewright has no service accounts. Every key acts for the one member
who created it, with that member's role at the moment of each request.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### Can I create an API key that belongs to the organization and not to a person?

No. A key always belongs to one member and one organization. When that
member leaves the organization, the key is revoked.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Where does an API key work?

At the REST API under `https://app.usetalewright.com/v1` and at the MCP
endpoint `https://app.usetalewright.com/mcp`. The same key works at both.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### Does an owner's API key have more rights than a member's API key?

Yes, within its scopes: a key acts with its member's role. An owner's key
with `files:write` changes files of the organization folder (the API's
library), and a member's key with the same scope does not. Browser-only
operations stay closed to both.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Is anything about an API key remembered between requests?

No. Each request is checked from scratch: whether the key is live, whether
its member still belongs to the organization, whether the member still
reaches the workspace, and what the member's role is now.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

## Creating a key

### How do I create an API key?

1. Open **Settings > Credentials** and press "Create API key".
2. Fill in "Name", "Organization", "Workspaces", "Permissions" and
   "Expires".
3. Press "Create key", then "Copy key" in the dialog "Copy your key".

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Where are API keys in the app?

Under **Settings > Credentials**. The page has the heading "Credentials" and
the table "Keys". With no keys it says "No API keys yet."

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Who can create an API key?

Every member of an organization: owners, admins and members. Each person
creates keys for themselves, for workspaces they reach.

More: [Credentials and scopes, Who can do what](../agents/credentials.md#who-can-do-what)

### Do I need a verified email address to create an API key?

No. A member needs no verified email to create a key. A verified email is
needed later, each time a key sets a file status.

More: [Credentials and scopes, Who can do what](../agents/credentials.md#who-can-do-what)

### Can an owner or admin create an API key for another member?

No. Everyone creates their own keys. Owners and admins can see and revoke
other members' keys, nothing more.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Can an API key be created with an API key?

No. Creating a key needs a person signed in with a browser. A key that calls
`POST /v1/me/api-keys` gets `403 FORBIDDEN` with reason `SESSION_REQUIRED`.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### What do I fill in when I create an API key?

Five things:

- "Name": where the key is used, 1 to 100 characters.
- "Organization": the organization the key works in.
- "Workspaces": 1 to 20 workspaces you reach.
- "Permissions": the scopes the key needs.
- "Expires": 30, 90, 180 or 365 days.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### What should I name an API key?

Name it after where it is used, such as a deploy script. The name is 1 to
100 characters and is what you and your organization's owners and admins see
in lists.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Can two API keys have the same name?

Yes. Nothing requires key names to be unique. Lists also show each key's
prefix, which tells two keys with one name apart.

More: [Credentials and scopes, The key list](../agents/credentials.md#the-key-list)

### Why is a workspace already ticked when I open the "Create API key" dialog?

You reach only one workspace of the chosen organization, so it is ticked for
you. With more than one, you tick them yourself.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Why is no permission ticked when I create an API key?

Nothing is ticked for you, on purpose. You tick only what the key needs. A
key with no permission cannot be created.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### What does "Write includes read." mean in the key dialog?

It means `files:write` includes `files:read`. A key that may change files
may also read them, so you need not tick both.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### What does "The key reaches these and the organization folder, and only while you do." mean?

The key works in the workspaces you tick and in the organization folder,
and in no other workspace. It does so only as long as you reach each of them
yourself. If you are removed from one, the key loses it at the next request.

More: [Credentials and scopes, When the member's access changes](../agents/credentials.md#when-the-members-access-changes)

### What happens after I press "Create key"?

The dialog "Copy your key" opens and shows the full key. This is the only
time it is shown. Press "Copy key", store it, then press "Done".

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Where should I store a new API key?

In a password manager or your deployment's secrets. The dialog says so:
"Store it in a password manager or your deployment's secrets."

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Can I see an API key again after I created it?

No. The full key is shown once, when it is created or rotated, and never
again, to anyone. Lists show only its prefix.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### I closed the dialog before copying my API key. How do I get the key?

You cannot get that secret back. Rotate the key to get a new secret, or
revoke it and create a new key.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### Does Talewright send an email when an API key is created?

Yes. Every new key is announced to its member by a security email.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### Can I turn off the email about a new API key?

No. It is a security email and cannot be turned off.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### What does the create operation return for a new API key?

`POST /v1/me/api-keys` answers `{ "apiKey": {...}, "token": "ak1_..." }`.
`apiKey` is the list entry of the key. `token` is the full key and is in
that one response only.

More: [Credentials and scopes, What a key list entry holds](../agents/credentials.md#what-a-key-list-entry-holds)

### Which properties does the request to create an API key take?

`name`, `organizationID`, `workspaceIDs` and `scopes` are required.
`expiresInDays` is optional: 30, 90, 180 or 365, default 90. The operation
is browser only.

More: [Credentials and scopes, Request bodies](../agents/credentials.md#request-bodies)

### What happens when a key's name ends with a line break?

The request is refused with `422 VALIDATION_FAILED` on `name`. The line
break is not silently trimmed.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### Are repeated scopes an error when a key is created?

No. Repeats in `scopes` are ignored. An unknown scope is refused with `422
VALIDATION_FAILED` on `scopes`.

More: [Credentials and scopes, Request bodies](../agents/credentials.md#request-bodies)

### What happens when I choose an organization I do not belong to for a key?

The request is refused with `422 VALIDATION_FAILED` on `organizationID`. In
the app the dialog says "Choose an organization you belong to."

More: [Credentials and scopes, Errors](../agents/credentials.md#errors)

### Is the response that carries a new API key cached anywhere?

No. Answers that carry a key are sent with `Cache-Control: no-store`.

More: [The REST API, Answers you must not cache](../agents/rest-api.md#answers-you-must-not-cache)

## The key itself

### What does a Talewright API key look like?

`ak1_<public ID>_<secret>`: the letters `ak1_`, 12 characters, `_`, then 43
characters. It is 60 characters in all.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### What is the prefix of an API key?

The visible start of the key, `ak1_<public ID>`. It identifies the key in
lists and stays the same when the key is rotated.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### Is the prefix of an API key a secret?

No. The prefix is not a secret. Only the part after it is.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### How do I send an API key with a request?

In the `Authorization` header, on every request:

```sh
curl https://app.usetalewright.com/v1/workspaces \
  -H "Authorization: Bearer $TALEWRIGHT_API_KEY"
```

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### Can I send an API key in the URL or in a cookie?

No. A key is sent only as `Authorization: Bearer ak1_...`. A script should
send no cookie at all.

More: [The REST API, Signing in with an API key](../agents/rest-api.md#signing-in-with-an-api-key)

### What happens if a request carries both my browser cookie and an API key?

At `/v1` it is refused with `401 UNAUTHENTICATED`, reason
`AMBIGUOUS_CREDENTIALS`. At `/mcp` cookies are ignored and the key is used.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### What happens when I send an API key to an operation that needs no sign-in?

The key is ignored, valid or not. The operation answers as it does for
anyone.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### Should I commit an API key to a repository?

No. Keep files that hold a key private and do not commit a key to a
project. Use your deployment's secrets or a password manager.

More: [MCP, Client setup](../agents/mcp.md#client-setup)

## Workspaces and reach

### Which workspaces can I tick when I create an API key?

1 to 20 workspaces of the chosen organization that you reach yourself at
that moment.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### Can an API key reach every workspace of the organization automatically?

No. A key lists 1 to 20 named workspaces and reaches only those. A workspace
created later is not added to it.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can I give an API key a workspace I cannot open myself?

No. The workspaces must be ones you reach. Otherwise the request is refused
with `422 VALIDATION_FAILED` on `workspaceIDs`.

More: [Credentials and scopes, Request bodies](../agents/credentials.md#request-bodies)

### Can I add or remove a workspace on an existing API key?

No. A key's workspaces cannot be edited. Create a new key with the
workspaces you need and revoke the old one.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### What does an API key get for a workspace it does not list?

`404 NOT_FOUND`, exactly like a workspace that does not exist. This holds
for IDs in paths, in request bodies, in cursors and in MCP resource
addresses.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can an agent with my API key read files in workspaces I did not grant?

No. A key reaches only the workspaces it lists, plus the organization
folder. Every other workspace answers `404 NOT_FOUND`.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can an API key tell whether a workspace exists outside its list?

No. A workspace outside the key and a workspace that does not exist answer
the same `404`, so the key cannot tell the difference.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### Does an API key reach the organization folder?

Yes, always. A key reaches the organization folder of its organization with
the same file scopes, whatever workspaces it is limited to. Its member's
role still decides: members read the organization folder, owners and admins
change it.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Why is the organization folder not in my key's workspace list?

The organization folder is shared by all workspaces of the organization, so
it is not a workspace. It is the shared root every member can open, and
every key reaches it without listing it.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can I keep an API key out of the organization folder?

No. Every key reaches the organization folder of its organization with its
file scopes, whatever workspaces it is limited to, because the organization
folder is the shared root every member can open. A key without `files:read`
or `files:write` reads no files there. To keep files away from members and
their keys, owners and admins put them in a workspace that only they are
invited to.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Can I limit an API key to one folder?

No. A key is limited by workspaces and scopes only. Inside a listed
workspace it reaches every folder its member reaches.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### Can I restrict an API key to certain IP addresses?

No. A key has a name, an organization, workspaces, scopes and an expiry,
and nothing else. To stop a key, revoke it.

More: [Credentials and scopes, Request bodies](../agents/credentials.md#request-bodies)

### Do file counts read with an owner's API key cover the whole organization?

No, and neither does a browser session. Each workspace and the organization
folder have their own statuses and fields, and a status's `fileCount` and
`publicFileCount` and the list's `noStatusFileCount` count only that
workspace's or organization folder's live files. A key reads the same counts
as its owner in a browser, except `trashedFileCount`, which is `null` for a
key.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### Does an API key see a file's duplicates in other workspaces?

Only in the key's own workspaces. Answers that span workspaces leave out
every workspace the key does not list.

More: [Credentials and scopes, What a credential reaches](../agents/credentials.md#what-a-credential-reaches)

### I was removed from one workspace my key lists. Does the whole key stop?

No. That workspace answers `404` from the next request. The key's other
workspaces keep working.

More: [Credentials and scopes, When the member's access changes](../agents/credentials.md#when-the-members-access-changes)

### I was added back to a workspace. Does my old API key reach it again?

Yes, from the next request, if the key lists that workspace.

More: [Credentials and scopes, When the member's access changes](../agents/credentials.md#when-the-members-access-changes)

### I was removed from every workspace my key lists. Is the key revoked?

No. The key stays live but reaches no workspace. It still reaches the
organization folder with its file scopes.

More: [Credentials and scopes, When the member's access changes](../agents/credentials.md#when-the-members-access-changes)

## Scopes

### Which scopes can an API key have?

Four: `workspace:read`, `files:read`, `files:write` and `files:approve`. A
key holds at least one.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Is there a wildcard scope or an "all" scope?

No. There are four scopes and no wildcard. A key that should do everything a
credential can do holds all four.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### What does `workspace:read` allow?

Reading the organization and its workspaces, the organization's members and
each listed workspace's members. It allows nothing about files.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Is there a `workspace:write` scope?

No. `workspace:read` has no write counterpart. Organizations, workspaces and
members are changed only in a browser.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### What does `files:read` allow?

Reading files, folders, tags, versions, uploads, library proposals,
statuses and fields. It also gives temporary URLs to download bytes,
thumbnails and previews, ZIP downloads, the counts of files by status, the
duplicate groups, the member's own favorites and the member's own hiding of
duplicate warnings.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Does `files:read` let a key download file content?

Yes. `files:read` gives temporary URLs for a version's bytes, thumbnail,
preview or playback, and ZIP downloads.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can a key with only `files:read` change anything?

Only the member's own favorites and which duplicate warnings the member
hid. Both need `files:read`, because they change nothing for anyone else.

More: [Roles and permissions, Edge cases](../reference/permissions.md#edge-cases)

### What does `files:write` allow?

Everything `files:read` allows, and:

- starting, completing and cancelling uploads;
- renaming, moving, tagging and describing files, and setting field values;
- creating, renaming, moving, trashing and restoring folders;
- trashing and restoring files;
- renaming and deleting tags, when the key's member is an owner or admin of
  that workspace or the organization folder;
- creating library proposals and rejecting their items.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Do I need to tick both `files:read` and `files:write`?

No. `files:write` includes `files:read`. A key with `files:write` needs no
separate `files:read`.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Does `files:write` let an agent delete files?

It lets an agent move files and folders to the trash, where they stay
restorable for 30 days. It does not let an agent delete anything for good.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Does `files:write` let a key set a file's status?

No. Setting or clearing a status needs `files:approve`, which no write scope
includes.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Does `files:write` let a key upload files?

Yes. Starting, completing and cancelling uploads need `files:write`.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Does `files:write` let a key set field values on files?

Yes. Setting field values needs `files:write`. Creating, renaming or
deleting the fields themselves is browser only.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Does `files:write` let a key reject a suggestion?

Yes. Creating library proposals and rejecting their items need
`files:write`. Applying a proposal is closed to every key.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### What does `files:approve` allow?

Setting or clearing the status of files. Together with `files:write` it
also allows a move that makes files public, and a restore that makes public
a file that was not public when it went to the trash.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Does `files:approve` include `files:write` or `files:read`?

No. It is separate in both directions. `files:approve` alone reads and
changes nothing besides statuses.

More: [Roles and permissions, Credentials and scopes](../reference/permissions.md#credentials-and-scopes)

### What can a key with only `files:approve` do?

It can set statuses on file IDs it is given. It cannot list or read files,
so it cannot find those IDs itself.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Which operations can every API key call, whatever its scopes?

Two: reading itself (`credential.read`, `GET /v1/credential`) and listing
the workspaces it reaches (`workspaces.list`, `GET /v1/workspaces`).

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### How many operations does each scope open?

`workspace:read` opens 4, `files:read` 42, `files:write` 30 more and
`files:approve` 2. Two more need no particular scope. That is 80 operations
a credential can call.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Which scope lets a key read the statuses and fields?

`files:read`, or `files:write`, which includes it. Each workspace and the
organization folder have their own lists. The operations are
`workspace.file_statuses.list`, `workspace.file_fields.list`,
`library.file_statuses.list` and `library.file_fields.list`.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can an API key create, rename or delete statuses and fields?

No. A key sets a status or a field value on files. It does not change the
lists of statuses, fields and choices: that needs a person in a browser.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Which scopes should I give an API key?

Only the ones its task needs. A key that only looks things up needs
`files:read`. A key that uploads or organizes needs `files:write`. Give
`files:approve` only to a key that must set statuses.

More: [MCP, Which tools a credential sees](../agents/mcp.md#which-tools-a-credential-sees)

### How do I make a read-only API key?

Tick only `files:read`, and `workspace:read` if the key should also read
the organization and its members. Such a key cannot change files.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can I add a scope to a key I already created?

No. Scopes cannot be edited later. Create a new key with the scopes you
need and revoke the old one.

More: [Credentials and scopes, What a credential is](../agents/credentials.md#what-a-credential-is)

### Do a key's scopes grow when I am promoted to admin?

No. The key acts with your new role from the next request, but its scopes
and workspaces stay as they were. A key without `files:approve` still
cannot set statuses.

More: [Credentials and scopes, When the member's access changes](../agents/credentials.md#when-the-members-access-changes)

### What does a key get when it lacks the scope an operation needs?

`403 FORBIDDEN` with reason `INSUFFICIENT_SCOPE`. `details.requiredScopes`
names the scope.

More: [Credentials and scopes, Errors](../agents/credentials.md#errors)

## `files:approve`

### What is `files:approve` for?

It is the authority to decide what may be public. A file is public only
while its status allows public use, so whoever sets statuses decides which
files can be public.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Why is `files:approve` not part of `files:write`?

An agent that may rename and move files must not, by that alone, be able to
open them to the world. So no write scope includes `files:approve`.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Who can give an API key `files:approve`?

Someone whose effective role is owner or admin in every workspace the key
lists. An organization owner or admin has that in every workspace.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Can a workspace admin who is only a member of the organization give a key `files:approve`?

Yes, when their workspace role is admin or owner in every workspace the key
lists.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### I am admin of one workspace and a member of another. Can one key for both hold `files:approve`?

No. You must be owner or admin in every listed workspace. Create one key
for the workspace where you are admin, with `files:approve`, and another
for the rest without it.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### Is `files:approve` ever ticked for me?

No. It must be chosen explicitly. Nothing preselects it, in the key dialog
or when an app asks to connect.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### What is "Set file statuses" in the key dialog?

It is the permission that gives the key the `files:approve` scope. It is
marked "(owner or admin only)" unless you are owner or admin in every
ticked workspace.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Is holding `files:approve` enough to set a status?

No. Each use also checks the member's role at that moment and that the
member's email is verified.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Which role is checked when a key sets a status?

For workspace files, the member's effective role in that workspace. For
organization folder files, the member's organization role. It must be owner
or admin.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Why can I set statuses in the browser but not with my API key?

Check three things: the key holds `files:approve`, you are still an owner or
admin of that workspace (or of the organization, for organization folder
files), and your email is verified. Through a credential, setting a status
needs a verified email; in a browser session it does not.

More: [Roles and permissions, Extra conditions](../reference/permissions.md#extra-conditions)

### Can a key with `files:approve` make a file public?

Not by itself. General access is set by a person in a browser. Setting a
status that allows public use makes a file public only when it sits in a
public folder, and then the change is refused with `409 CONFLICT`, reason
`VISIBILITY_CHANGE`, until it is repeated with `confirmVisibilityChange:
true`.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### When does moving a file need `files:approve`?

When the move would make files public: moving a file with an allowing
status into a public folder, or moving a folder under a public folder. It
is needed together with `files:write`.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### When does restoring from the trash need `files:approve`?

When the restore would make public a file that was not public when it went
to the trash. Every other restore needs only `files:write`.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Does a file that was public when it was trashed come back public without `files:approve`?

Yes. A file that was public when it went to the trash comes back public for
any credential that may restore it.

More: [Credentials and scopes, `files:approve`](../agents/credentials.md#filesapprove)

### Can a key clear a file's status?

Yes, with `files:approve`. Sending `statusID: null` clears the status, which
also stops the file's public link.

More: [MCP, Worked examples](../agents/mcp.md#worked-examples)

### Does a key with `files:approve` and `files:write` still have to confirm a move into a public folder?

Yes. With both scopes and an owner or admin behind the key, the move still
needs `confirmVisibilityChange: true`.

More: [Roles and permissions, Edge cases](../reference/permissions.md#edge-cases)

## What a key can never do

### What can no API key do, whatever its scopes?

- Make a file or folder public or restricted.
- Delete for good, or empty the trash.
- Apply a library proposal.
- Create, rotate, revoke or list credentials, or read their activity.
- Manage accounts, sessions, organizations, workspaces and people.
- Manage statuses and fields.
- Export the organization.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an API key make a file or a folder public?

No. General access is set in the browser by an owner or admin. No
credential creates a public link.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an API key make a public file restricted again?

Not through general access, which is browser only. A key with
`files:approve` can stop a public link by setting a status that does not
allow public use, or by clearing the status.

More: [MCP, Worked examples](../agents/mcp.md#worked-examples)

### Can an API key delete a file for good?

No. A key can move files and folders to the trash, where they stay
restorable. Purging a trashed file or folder needs a person in a browser.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an API key empty the trash?

No. Emptying the trash is permanent deletion and is browser only.

More: [Roles and permissions, What only a person in a browser can do](../reference/permissions.md#what-only-a-person-in-a-browser-can-do)

### Can an API key apply a suggestion?

No. An agent proposes; a person applies. A key that tries gets `403
FORBIDDEN` with reason `HUMAN_APPROVAL_REQUIRED`.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an API key list or revoke other API keys?

No. Listing, creating, rotating and revoking credentials always need a
person in a browser. A credential can never create, extend or recover a
credential, an account or access.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Can an API key revoke itself?

No. Revoking a key is browser only: its member revokes it under **Settings >
Credentials**, or an owner or admin in Key management.

More: [Credentials and scopes, Operations](../agents/credentials.md#operations)

### Can an API key read its own activity?

No. Reading credential activity needs a browser session. A key can read
what it is and what it reaches with `GET /v1/credential`.

More: [Audit trail, For agents](../reference/audit-trail.md#for-agents)

### What does a key with every scope get on a browser-only operation?

`403 FORBIDDEN` with reason `SESSION_REQUIRED`, or
`HUMAN_APPROVAL_REQUIRED` for applying a proposal. Scopes do not open
browser-only operations.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Why are some actions closed to every API key?

The product draws that line on purpose. An agent can prepare work, do
reversible work and, with an explicit scope, set statuses. It cannot give
itself more access, open files to the public, or destroy anything for good.

More: [The REST API, What "needs a person in a browser" means](../agents/rest-api.md#what-needs-a-person-in-a-browser-means)

### How many operations are closed to every API key?

78 of the 172 operations need a person in a browser. Another 12 need no
sign-in at all. The remaining 82 are open to a key that holds the scope.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

## Expiry

### Which expiry can I choose for a new API key?

"In 30 days", "In 90 days", "In 180 days" or "In 365 days". "In 90 days" is
preselected.

More: [Credentials and scopes, Create a key](../agents/credentials.md#create-a-key)

### Can I create an API key that never expires?

No. There are no keys without an expiry. The longest lifetime is 365 days.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### Can I extend the expiry of an API key?

No. The expiry cannot be extended. Create a new key before the old one
expires.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### Does rotating an API key move its expiry?

No. Rotating gives the key a new secret. The expiry stays the same.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### What happens when an API key expires?

It answers `401 UNAUTHENTICATED` with reason `INVALID_TOKEN` at once.
Create a new key.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### Where do I see when my API key expires?

In the "Expires" column of the table "Keys" under **Settings >
Credentials**. An agent reads `expiresAt` from `GET /v1/credential`.

More: [Credentials and scopes, The key list](../agents/credentials.md#the-key-list)

### What does "Expired" mean next to a key?

The key's lifetime ran out and it no longer works. The row shows "Expired"
with the date, and has no "Rotate" button. Your own list and Key management
mark it the same way, for 30 days after it expired.

More: [Credentials and scopes, The key list](../agents/credentials.md#the-key-list)

### Can I rotate an expired API key?

No. An expired key cannot be rotated: the request answers `404 NOT_FOUND`.
Create a new key.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### Can I revoke an expired API key?

Yes, from your own list or, as an owner or admin, from Key management.
Revoking an expired key removes it from both lists.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### Does Key management show expired keys?

Yes. An expired key or connected app stays in Key management for 30 days,
marked "Expired" with the expiry date, exactly as its member's own list marks
it. 30 days after the expiry both lists drop it. Revoked ones are in neither
list.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

### How do I renew an API key that is about to expire?

Create a new key with the same workspaces and scopes, switch your script or
agent to it, then revoke the old one. A key's own expiry cannot be moved.

More: [Credentials and scopes, Expiry](../agents/credentials.md#expiry)

## Last used and activity

### What does "Last used" show for an API key?

When the key last made a request. It is refreshed at most once a minute. An
API reads it as `lastUsedAt`.

More: [Credentials and scopes, Last used and last client](../agents/credentials.md#last-used-and-last-client)

### What does "Never used" mean on a key?

The key has not made a single request yet.

More: [Credentials and scopes, Last used and last client](../agents/credentials.md#last-used-and-last-client)

### What is the "last client" of an API key?

The MCP client that last connected with the key: its name, its version and
the MCP protocol version. It is `null` until an MCP client connects.

More: [Credentials and scopes, Last used and last client](../agents/credentials.md#last-used-and-last-client)

### How do I see what was done with my API key?

Open **Settings > Credentials** and press "Activity" on the key's row. A
side sheet titled "Activity of {name}" lists each action with its workspace
and time, newest first.

More: [Audit trail, In the app](../reference/audit-trail.md#in-the-app)

### What does one activity entry of a key hold?

An `id`, `occurredAt`, the `action` such as `folder.created`, the
`targetType`, the `targetID` and the `workspace` with its ID and name.

More: [Audit trail, Credential activity](../reference/audit-trail.md#credential-activity)

### Why is the workspace empty on some activity entries?

`workspace` is `null` for events without a workspace, such as changes to
organization folder files, and for a workspace that has since been deleted.

More: [Audit trail, Credential activity](../reference/audit-trail.md#credential-activity)

### Is creating, rotating or revoking a key shown in the key's activity?

No. Activity lists what was done with the key. Creating, rotating and
revoking happen in a browser session, so they are not in the key's own
activity.

More: [Audit trail, Credential activity](../reference/audit-trail.md#credential-activity)

### Does reading or downloading files with a key show in its activity?

Reading does not. Asking for a ZIP download records
`files.archive_downloaded`. Single signed URLs are not recorded.

More: [Audit trail, Rules](../reference/audit-trail.md#rules)

### Does a refused request show in a key's activity?

No. A request that is refused and changes nothing records nothing.

More: [Audit trail, Rules](../reference/audit-trail.md#rules)

### Does a revoked API key keep its activity?

Yes. A revoked key keeps its activity. Revoking hides nothing.

More: [Audit trail, Credential activity](../reference/audit-trail.md#credential-activity)

### What does a key's activity show before the key is used?

Nothing. The sheet says "Nothing has been done with it yet."

More: [Audit trail, In the app](../reference/audit-trail.md#in-the-app)

### Does a key's activity show the file an upload created?

Yes. The file is created after verification, in the background, and its
`file.created` carries the key that completed the upload. The activity
shows `upload.created`, `upload.completed` and `file.created`.

More: [Audit trail, Credential activity](../reference/audit-trail.md#credential-activity)

### Does a change made with a key name the member or the key?

Both. The event names the member the key acts for, and carries the key's ID
and its kind, `api_key`.

More: [Audit trail, What an event holds](../reference/audit-trail.md#what-an-event-holds)

### Can I export or download a key's activity?

No. Activity is read in the app, page by page with "Load more". There is no
export of it, and the organization export does not contain the audit trail.

More: [Audit trail, Questions and answers](../reference/audit-trail.md#questions-and-answers)

## Rotating

### What does rotating an API key do?

It gives the key a new secret, shown once. The prefix, the name, the
workspaces, the scopes and the expiry stay the same.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### How do I rotate an API key?

1. Press "Rotate" on the key's row under **Settings > Credentials**.
2. Choose under "Keep the old secret working".
3. Press "Rotate key". "Copy your key" shows the new key once.

More: [Credentials and scopes, Rotate a key](../agents/credentials.md#rotate-a-key)

### Does the old secret stop working when I rotate a key?

By default, yes, at once. "No, stop it now" is preselected.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### Can I keep the old secret working for a while after rotating?

Yes, for up to 24 hours. The app offers "For 1 hour", "For 6 hours" and
"For 24 hours". Through the operation, `overlapHours` takes 0 to 24.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### How do I replace a key's secret in a running deployment without a gap?

Rotate with an overlap. The old secret keeps working for the hours you
choose while you deploy the new one.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### What does "Old secret until ..." mean on a key?

A rotated-out secret of that key still works, and the time says when it
stops. The API gives it as `previousSecretExpiresAt`.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### What happens when I rotate a key twice in a row?

Rotating again shortens every older secret that still works to the new
overlap. Rotating with no overlap stops them all at once.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### Can an old secret keep working after the key itself expires?

No. An old secret never works past the key's own expiry, whatever overlap
was chosen.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### Who can rotate an API key?

Only the key's member. Owners and admins cannot rotate another member's
key; they can revoke it.

More: [Credentials and scopes, Rotating](../agents/credentials.md#rotating)

### Does rotating change the key's prefix?

No. The prefix stays the same when the key is rotated, so lists and
activity keep pointing at the same key.

More: [Credentials and scopes, The key itself](../agents/credentials.md#the-key-itself)

### Should I rotate or revoke a key I no longer trust?

Revoke it, or rotate it with "No, stop it now". Both stop the old secret at
once. Revoking also stops any older secret still in an overlap.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### What does the dialog "Rotate {name}?" say?

"The key gets a new secret, shown once. Its permissions and expiry stay the
same."

More: [Credentials and scopes, Rotate a key](../agents/credentials.md#rotate-a-key)

## Revoking

### How do I revoke an API key?

Press "Revoke" on the key's row under **Settings > Credentials**, then
"Revoke key". The row disappears and "Revoked {name}" confirms.

More: [Credentials and scopes, Revoke a key](../agents/credentials.md#revoke-a-key)

### What happens the moment an API key is revoked?

It answers `401 UNAUTHENTICATED` with reason `INVALID_TOKEN` at once,
including any old secret still in its overlap. Anything using the key stops
working.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Can I undo revoking an API key?

No. Revoking cannot be undone. Create a new key instead.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Who can revoke an API key?

Its member, or an owner or admin of its organization.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### When is an API key revoked automatically?

When its member:

- leaves the organization or is removed from it (that organization's keys
  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.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Does a password reset revoke my keys in every organization?

Yes. Every key of the member stops, in every organization. New keys must be
created afterwards.

More: [Credentials and scopes, Edge cases](../agents/credentials.md#edge-cases)

### Does revoking a key undo what was done with it?

No. Revoking only stops the key. What was done with it stays, and stays
readable as its activity.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Does a revoked key still show in a list?

No. A revoked key leaves every list: yours and Key management.

More: [Credentials and scopes, Revoking](../agents/credentials.md#revoking)

### Can I tell from the error whether a key expired or was revoked?

No. Both answer `401 UNAUTHENTICATED` with reason `INVALID_TOKEN`. One
answer covers every cause.

More: [Errors, `UNAUTHENTICATED` (401)](../reference/errors.md#unauthenticated-401)

### What does the dialog "Revoke {name}?" say?

"Anything using this key stops working at once. This cannot be undone."

More: [Credentials and scopes, Revoke a key](../agents/credentials.md#revoke-a-key)

## Oversight by owners and admins

### What is Key management?

The organization settings page where owners and admins see every member's
API keys and connected apps, read their activity and revoke them. Revoked
ones are not listed. Expired ones stay listed for 30 days, marked "Expired".

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Where do owners and admins find Key management?

Open the organization's settings and follow "Key management". The table
"Credentials" has the columns "Key", "Member", "Permissions" and "Expires".

More: [Credentials and scopes, Key management (owners and admins)](../agents/credentials.md#key-management-owners-and-admins)

### What do owners and admins see about a member's API key?

The name, the prefix, the member, the workspaces, the scopes, the expiry,
when it was last used and its activity. They never see a secret.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Can an owner or admin use a member's API key?

No. Nobody sees a key's secret after it was created, so nobody else can use
it.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Can an owner revoke a member's API key without asking?

Yes. Owners and admins can revoke any member's key. The member is not
asked, and the key's row disappears from the member's list too.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### What does the confirmation say when an owner revokes a member's key?

"{member}'s key stops working at once. They can create a new one if they
still need it." It is confirmed with "Revoke key".

More: [Credentials and scopes, Key management (owners and admins)](../agents/credentials.md#key-management-owners-and-admins)

### Can an owner change what a member's API key reaches?

No. Owners and admins cannot create a key for another member, rotate
another member's key or change what it reaches. They can revoke it.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Can owners and admins read what a member's API key did?

Yes. "Activity" on any credential in Key management shows what was done
with it.

More: [Audit trail, In the app](../reference/audit-trail.md#in-the-app)

### Does Key management list connected apps as well as API keys?

Yes. A connected app reads "Connected app from {host}" under its name, in
the same table, with "Connected {date and time}". Each connection is a row
of its own.

More: [Credentials and scopes, Key management (owners and admins)](../agents/credentials.md#key-management-owners-and-admins)

### Does revoking my own key from Key management count as an admin revoking it?

No. Revoking your own credential from that page counts as revoking it
yourself. The recorded reason is `user`, not `admin`.

More: [Audit trail, Credentials](../reference/audit-trail.md#credentials)

### Which reasons are recorded when an API key is revoked?

`user`, `admin`, `membership_removed`, `password_reset`, `password_changed`
or `user_deleted`. The event `api_key.revoked` notes the reason and the
key's member.

More: [Audit trail, Credentials](../reference/audit-trail.md#credentials)

### Can an organization stop its members from creating API keys?

No. Every member can create keys for the workspaces they reach. Owners and
admins see each key in Key management and can revoke it.

More: [Credentials and scopes, Who can do what](../agents/credentials.md#who-can-do-what)

### How does an owner learn that a member created a key?

The key shows in Key management with its member, workspaces, scopes and
expiry. The security email about a new key goes to the key's member.

More: [Credentials and scopes, Oversight by owners and admins](../agents/credentials.md#oversight-by-owners-and-admins)

### Which operations are behind Key management?

`GET /v1/organizations/{organizationID}/credentials` lists,
`DELETE /v1/organizations/{organizationID}/credentials/{credentialID}`
revokes, and `.../credentials/{credentialID}/activity` reads activity. All
three are browser only.

More: [Credentials and scopes, Operations](../agents/credentials.md#operations)

## Security

### What can someone do with a leaked API key?

Exactly what its scopes allow, in its workspaces and the organization
folder, as its member, until the key is revoked or expires. They cannot make
files public, delete for good, or manage people and credentials.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### What should I do when an API key leaked?

Open its "Activity" under **Settings > Credentials** to see what was done
with it, then press "Revoke". The key stops at once. Create a new key for
whatever still needs one.

More: [Credentials and scopes, Revoke a key](../agents/credentials.md#revoke-a-key)

### How do I keep the damage of a leaked key small?

Give each key only the workspaces and scopes its task needs, choose a short
expiry, and leave out `files:approve` unless the key must set statuses.

More: [Credentials and scopes, Scopes](../agents/credentials.md#scopes)

### Can a leaked key be used to take over my account?

No. A key cannot change your name, password or email address, manage your
sessions, or create or extend a credential. Those need a person in a
browser.

More: [Credentials and scopes, What no credential can do](../agents/credentials.md#what-no-credential-can-do)

### Do audit events or activity ever contain an API key?

No. An event never holds passwords, API keys, tokens or signed URLs. It
carries the credential's ID and kind.

More: [Audit trail, What an event never holds](../reference/audit-trail.md#what-an-event-never-holds)

### What happens when wrong API keys keep being sent from my network?

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.

More: [Credentials and scopes, Rate limits](../agents/credentials.md#rate-limits)

### Do two keys of the same member share one rate limit?

No. Each key has its own 600 requests a minute. All credentials of one
organization together share 3,000 a minute.

More: [Credentials and scopes, Rate limits](../agents/credentials.md#rate-limits)

## Reading a key from the inside

### How do I find out what an API key can do, from the key alone?

Call `GET /v1/credential` with the key, or the MCP tool `credential_read`.
It takes no parameters.

More: [Credentials and scopes, Reading the presented credential](../agents/credentials.md#reading-the-presented-credential)

### What does `GET /v1/credential` return?

The credential's `id`, `kind`, `name`, the `user` it acts for, its
`organization`, its `workspaces`, its `scopes`, `expiresAt` and `client`.
`client` is `null` for an API key.

More: [Credentials and scopes, Reading the presented credential](../agents/credentials.md#reading-the-presented-credential)

### Why does `GET /v1/credential` list fewer workspaces than I ticked?

`workspaces` lists only the key's workspaces the member still reaches. A
workspace you were removed from, or one that was deleted, is left out.

More: [Credentials and scopes, Reading the presented credential](../agents/credentials.md#reading-the-presented-credential)

### How does a script tell an API key from a connected app?

By `kind` in `GET /v1/credential`: `api_key` or `connected_app`. For a
connected app, `client` holds the app's `clientID` and `name`.

More: [Credentials and scopes, Reading the presented credential](../agents/credentials.md#reading-the-presented-credential)

### What does an entry in the key list hold?

`id`, `kind`, `name`, `prefix`, `client`, `lastClient`, `user`,
`organizationID`, `workspaceIDs`, `scopes`, `createdAt`, `expiresAt`,
`lastUsedAt` and `previousSecretExpiresAt`. It never holds the secret.

More: [Credentials and scopes, What a key list entry holds](../agents/credentials.md#what-a-key-list-entry-holds)

### In what order are my API keys listed?

Newest first. The list answers `{ "items": [...], "nextCursor": ... }`, and
the app shows more with "Load more".

More: [Credentials and scopes, What a key list entry holds](../agents/credentials.md#what-a-key-list-entry-holds)

### Which operations manage API keys?

`GET /v1/me/api-keys` lists, `POST /v1/me/api-keys` creates,
`POST /v1/me/api-keys/{keyID}/rotate` rotates and
`DELETE /v1/me/api-keys/{keyID}` revokes. All four are browser only: the
web app calls them for a signed-in person.

More: [Credentials and scopes, Operations](../agents/credentials.md#operations)

### What do the three columns of the "Keys" table show?

"Key" shows the name and the prefix. "Access" shows the organization, the
workspaces and the scopes. "Expires" shows the expiry date, with "Last used
{time}" or "Never used" below it.

More: [Credentials and scopes, The key list](../agents/credentials.md#the-key-list)
