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.
The basics
- What is an API key in Talewright?
- What is the difference between a credential and an API key?
- Who does an API key act for?
- Is an API key a service account?
- Can I create an API key that belongs to the organization and not to a person?
- Where does an API key work?
- Does an owner's API key have more rights than a member's API key?
- Is anything about an API key remembered between requests?
Creating a key
- How do I create an API key?
- Where are API keys in the app?
- Who can create an API key?
- Do I need a verified email address to create an API key?
- Can an owner or admin create an API key for another member?
- Can an API key be created with an API key?
- What do I fill in when I create an API key?
- What should I name an API key?
- Can two API keys have the same name?
- Why is a workspace already ticked when I open the "Create API key" dialog?
- Why is no permission ticked when I create an API key?
- What does "Write includes read." mean in the key dialog?
- What does "The key reaches these and the organization folder, and only while you do." mean?
- What happens after I press "Create key"?
- Where should I store a new API key?
- Can I see an API key again after I created it?
- I closed the dialog before copying my API key. How do I get the key?
- Does Talewright send an email when an API key is created?
- Can I turn off the email about a new API key?
- What does the create operation return for a new API key?
- Which properties does the request to create an API key take?
- What happens when a key's name ends with a line break?
- Are repeated scopes an error when a key is created?
- What happens when I choose an organization I do not belong to for a key?
- Is the response that carries a new API key cached anywhere?
The key itself
- What does a Talewright API key look like?
- What is the prefix of an API key?
- Is the prefix of an API key a secret?
- How do I send an API key with a request?
- Can I send an API key in the URL or in a cookie?
- What happens if a request carries both my browser cookie and an API key?
- What happens when I send an API key to an operation that needs no sign-in?
- Should I commit an API key to a repository?
Workspaces and reach
- Which workspaces can I tick when I create an API key?
- Can an API key reach every workspace of the organization automatically?
- Can I give an API key a workspace I cannot open myself?
- Can I add or remove a workspace on an existing API key?
- What does an API key get for a workspace it does not list?
- Can an agent with my API key read files in workspaces I did not grant?
- Can an API key tell whether a workspace exists outside its list?
- Does an API key reach the organization folder?
- Why is the organization folder not in my key's workspace list?
- Can I keep an API key out of the organization folder?
- Can I limit an API key to one folder?
- Can I restrict an API key to certain IP addresses?
- Do file counts read with an owner's API key cover the whole organization?
- Does an API key see a file's duplicates in other workspaces?
- I was removed from one workspace my key lists. Does the whole key stop?
- I was added back to a workspace. Does my old API key reach it again?
- I was removed from every workspace my key lists. Is the key revoked?
Scopes
- Which scopes can an API key have?
- Is there a wildcard scope or an "all" scope?
- What does
workspace:readallow? - Is there a
workspace:writescope? - What does
files:readallow? - Does
files:readlet a key download file content? - Can a key with only
files:readchange anything? - What does
files:writeallow? - Do I need to tick both
files:readandfiles:write? - Does
files:writelet an agent delete files? - Does
files:writelet a key set a file's status? - Does
files:writelet a key upload files? - Does
files:writelet a key set field values on files? - Does
files:writelet a key reject a suggestion? - What does
files:approveallow? - Does
files:approveincludefiles:writeorfiles:read? - What can a key with only
files:approvedo? - Which operations can every API key call, whatever its scopes?
- How many operations does each scope open?
- Which scope lets a key read the statuses and fields?
- Can an API key create, rename or delete statuses and fields?
- Which scopes should I give an API key?
- How do I make a read-only API key?
- Can I add a scope to a key I already created?
- Do a key's scopes grow when I am promoted to admin?
- What does a key get when it lacks the scope an operation needs?
files:approve
- What is
files:approvefor? - Why is
files:approvenot part offiles:write? - Who can give an API key
files:approve? - Can a workspace admin who is only a member of the organization give a key
files:approve? - I am admin of one workspace and a member of another. Can one key for both hold
files:approve? - Is
files:approveever ticked for me? - What is "Set file statuses" in the key dialog?
- Is holding
files:approveenough to set a status? - Which role is checked when a key sets a status?
- Why can I set statuses in the browser but not with my API key?
- Can a key with
files:approvemake a file public? - When does moving a file need
files:approve? - When does restoring from the trash need
files:approve? - Does a file that was public when it was trashed come back public without
files:approve? - Can a key clear a file's status?
- Does a key with
files:approveandfiles:writestill have to confirm a move into a public folder?
What a key can never do
- What can no API key do, whatever its scopes?
- Can an API key make a file or a folder public?
- Can an API key make a public file restricted again?
- Can an API key delete a file for good?
- Can an API key empty the trash?
- Can an API key apply a suggestion?
- Can an API key list or revoke other API keys?
- Can an API key revoke itself?
- Can an API key read its own activity?
- What does a key with every scope get on a browser-only operation?
- Why are some actions closed to every API key?
- How many operations are closed to every API key?
Expiry
- Which expiry can I choose for a new API key?
- Can I create an API key that never expires?
- Can I extend the expiry of an API key?
- Does rotating an API key move its expiry?
- What happens when an API key expires?
- Where do I see when my API key expires?
- What does "Expired" mean next to a key?
- Can I rotate an expired API key?
- Can I revoke an expired API key?
- Does Key management show expired keys?
- How do I renew an API key that is about to expire?
Last used and activity
- What does "Last used" show for an API key?
- What does "Never used" mean on a key?
- What is the "last client" of an API key?
- How do I see what was done with my API key?
- What does one activity entry of a key hold?
- Why is the workspace empty on some activity entries?
- Is creating, rotating or revoking a key shown in the key's activity?
- Does reading or downloading files with a key show in its activity?
- Does a refused request show in a key's activity?
- Does a revoked API key keep its activity?
- What does a key's activity show before the key is used?
- Does a key's activity show the file an upload created?
- Does a change made with a key name the member or the key?
- Can I export or download a key's activity?
Rotating
- What does rotating an API key do?
- How do I rotate an API key?
- Does the old secret stop working when I rotate a key?
- Can I keep the old secret working for a while after rotating?
- How do I replace a key's secret in a running deployment without a gap?
- What does "Old secret until ..." mean on a key?
- What happens when I rotate a key twice in a row?
- Can an old secret keep working after the key itself expires?
- Who can rotate an API key?
- Does rotating change the key's prefix?
- Should I rotate or revoke a key I no longer trust?
- What does the dialog "Rotate {name}?" say?
Revoking
- How do I revoke an API key?
- What happens the moment an API key is revoked?
- Can I undo revoking an API key?
- Who can revoke an API key?
- When is an API key revoked automatically?
- Does a password reset revoke my keys in every organization?
- Does revoking a key undo what was done with it?
- Does a revoked key still show in a list?
- Can I tell from the error whether a key expired or was revoked?
- What does the dialog "Revoke {name}?" say?
Oversight by owners and admins
- What is Key management?
- Where do owners and admins find Key management?
- What do owners and admins see about a member's API key?
- Can an owner or admin use a member's API key?
- Can an owner revoke a member's API key without asking?
- What does the confirmation say when an owner revokes a member's key?
- Can an owner change what a member's API key reaches?
- Can owners and admins read what a member's API key did?
- Does Key management list connected apps as well as API keys?
- Does revoking my own key from Key management count as an admin revoking it?
- Which reasons are recorded when an API key is revoked?
- Can an organization stop its members from creating API keys?
- How does an owner learn that a member created a key?
- Which operations are behind Key management?
Security
- What can someone do with a leaked API key?
- What should I do when an API key leaked?
- How do I keep the damage of a leaked key small?
- Can a leaked key be used to take over my account?
- Do audit events or activity ever contain an API key?
- What happens when wrong API keys keep being sent from my network?
- Do two keys of the same member share one rate limit?
Reading a key from the inside
- How do I find out what an API key can do, from the key alone?
- What does
GET /v1/credentialreturn? - Why does
GET /v1/credentiallist fewer workspaces than I ticked? - How does a script tell an API key from a connected app?
- What does an entry in the key list hold?
- In what order are my API keys listed?
- Which operations manage API keys?
- What do the three columns of the "Keys" table show?