What is a key scope?
A key scope is a limit on what one API key is allowed to do, such as only reading messages, only writing drafts, or managing accounts.
Also called: Permission scope.
In plain words
When you hand a spare house key to a neighbour, you might give them one that only opens the front door, not the safe. A key scope is the same idea for software.
Each key is given a short list of things it may do, and nothing more.
This is handy when you use more than one tool. A reporting tool only needs to read, so it gets a key that can only read. An agent that answers customers needs to reply, so its key can reply.
Neither needs the power to change your account settings.
Scopes also make mistakes smaller. If a key with a narrow scope is lost or misused, the damage is limited to what that scope allows. That is why it is good practice to give each tool the least it needs to do its job.
If a key tries something outside its scope, the service refuses and says which permission is missing. Nothing is done, and you can decide whether to widen it.
How it works in Spaces
Spaces keys carry scopes such as read, messages:send and accounts:manage. Setting up or changing the business brief and connecting accounts need accounts:manage.
A key with the messages:draft scope is draft-only. Its replies, new chats, posts and comments always wait for your approval, even when approvals are off for the workspace.
On top of scopes, every agent has its own permissions, accounts and pause, set by the owner under Your agent.
Related terms
- API key: An API key is a long secret code that proves to a service that a request comes from you, so it works like a password for software rather than for people.
- Bearer token: A bearer token is a secret code that a program sends with each request to prove it is allowed in, like a key card that opens any door it fits.
- AI agent: An AI agent is an AI model, such as ChatGPT, Claude or Grok, that can take actions with tools you give it, like reading a message and sending a reply, rather than only chatting.
- Hand-over: A hand-over is when an AI agent stops replying in a conversation and passes it to a person, because the customer needs judgement, care or a decision the AI should not make.
FAQ
What is a draft-only key?
A key with the messages:draft scope. Everything it writes waits for your approval before anything is sent.
What happens if a key goes beyond its scope?
Spaces refuses the request and says which scope is missing. Nothing is sent or changed.
Should every tool get its own key?
It is a good habit. Separate keys let you pause or remove one tool without touching the others.
Can an agent give itself more access?
No. An agent cannot change its own access or hand out permissions it does not have.
Useful next: Account safety, API reference, AI agents that work with Spaces. Every term: the glossary.