Roles
Every member of a workspace holds exactly one role, from a closed set: owner, admin, developer or viewer. A role is a set of permissions rather than a rank, so it is worth reading the table rather than assuming that each row contains the one below it.
A developer may create a key because a developer who cannot get a credential
cannot use the product. A viewer holds the read permissions and their own key
list, and creates nothing.
Two rules sit above the table and cannot be worked around by editing a role:
Nobody can hand out authority they do not hold themselves. An attempt is
refused with:
You cannot give somebody permissions you do not have yourself.
Only the owner makes or unmakes an admin. An admin creating a second admin
would confer no new permission, but it would confer persistence, and a stolen
admin session must not be able to leave a permanent second administrator behind
after the session is ended and the password is changed. The refusal reads:
Only the workspace owner can make someone an admin.
Exactly one owner
A workspace has exactly one owner, always. That is a two-sided rule. Ownership is never granted. Trying to set somebody’s role to owner, or to move the current owner out of the owner role, is refused with:Ownership is transferred, never granted. Use the transfer control instead.
Ownership moves by transfer, which promotes the new owner and demotes the
outgoing one in the same write. There is no moment in which the workspace has
two owners or none. A removal or a demotion that would leave the workspace with
no owner is refused, and the refusal names transfer as the way through.
The owner and money
Money reads are the workspace’s. Money writes are the owner’s. Any member, whatever their role, may read the balance, read the statement, and see whether the owner has paused requests. Those three facts govern whether a member’s own requests will be served, and a member who cannot see the balance discovers it by having a request refused. Buying credit, managing the card, and pausing or resuming requests are the owner’s alone. Every billing control answers a non-owner with one sentence:Only the workspace owner can manage its billing: the card and the buying of credit are the owner’s own. Members may read the balance and the statement of the workspace they are in.Pause has its own sentence, because the fact it refuses is not billing:
Only the workspace owner can pause or resume its requests.Both are HTTP 403. The refusal names what your role does not cover rather than pretending the control is not there, because the screen offered it and an unexplained absence leaves you with nothing to act on. One consequence is worth stating plainly: because billing belongs to a workspace, one card cannot fund two workspaces. Each workspace is bought for separately.
Invitations
An owner or an admin invites somebody by email address.- The invitation is bound to that address. The link works for that address and no other.
- It is valid for seven days.
- It can offer admin, developer or viewer. It can never offer owner, because ownership moves only by transfer.
- Only the owner can offer admin, by the persistence rule above.
- It confers nothing until it is accepted, and the inviter’s authority is re-checked at redemption. An invitation is a credential minted by somebody who may since have lost the right to mint one.
- It may carry a key reservation, so a person arrives with a key waiting for them. The reservation occupies one of the workspace’s five key slots from the moment it is made. See Create an API key.
- A workspace may hold up to ten pending invitations at once.
Keys and who can see them
A key belongs to the workspace. It also carries one accountable member, so spend can be attributed to somebody. A key may be limited to named members of its workspace. That limit decides who can see the key exists and who can manage it. The owner and admins always see every key. Everybody else sees the keys they are accountable for or named on, and nobody outside the list learns that such a key exists. The limit is visibility and management, and nothing else. On the request path a key is a bearer credential: whoever holds the secret can call the API with it. So the limit is not per-person enforcement, and it deliberately promises no per-person usage split. Requests made with a shared key cannot be attributed to the individual who sent them, because what reached us was the key. The one place a member limit does more than scope a screen is the playground, where sending as a key is treated as managing it. See Playground.Removing somebody never silently revokes a key
Removal is blocked until every live key the departing member is accountable for carries an explicit choice: revoke it now, or keep it and name a new accountable member. There is no default, because the safest-looking default is still a choice nobody made. Exactly three things revoke a key, and the list is closed:- Somebody explicitly revoked it.
- It was replaced, which mints a new key and ends the old one in the same motion.
- Somebody was removed from the workspace and the person removing them chose revoke for that key.
Next
Create a workspace
Open one from the workspace switcher, and see what you get on day one.
Invite and manage members
Invite somebody, change a role, transfer ownership or remove somebody.