Every request to the API and the MCP server needs an API key. A key belongs to one workspace, acts as the owner or admin who created it, and can only reach the endpoints its scopes allow. Keys look like gr_live_ followed by 43 letters, digits, hyphens and underscores.
Create a key
- 1
Open API and agents
In Gradiently, go to Settings › API and agents and choose the workspace the key is for. Only owners and admins of that workspace can create keys.
- 2
Name it
Under Create a key, give it a Name after where you'll use it, such as Claude Code or Nightly export, so you know which one to revoke later.
- 3
Choose what it can do
Under What it can do, select the permissions it needs, at least one. The next section explains each.
- 4
Copy it once
Select Create key. The key appears in Copy your key now, and this is the only time it is shown. Copy it into a password manager or your secret store, then select I've saved it.
Whoever created a key gets an email when it is made and when it is revoked, with its name, the start of the key and its permissions. The list in Settings shows each live key's name, the start of the key, when it was last used and how many permissions it has.
Scopes
A scope is one permission. A request needs every scope its endpoint lists, and each MCP tool needs the scopes of all the requests it makes. Grant only what the job needs.
| Scope | In Settings | What it allows |
|---|---|---|
designs:read | Read designs | Read brands, designs, thumbnails and uploads, render designs, and follow Designer sets. |
designs:write | Create and edit designs | Create, change, duplicate, share and delete designs, upload and delete images, and run the Designer. |
marks:read | Search Marks | Search the Market, read Marks and your drafts, build and review recipes, and read Mark versions. |
marks:claim | Claim Marks | Claim an available Mark, or one another owner has listed, for the key's creator. |
brand:generate | Generate brands | Generate and adopt brands, save and change draft Marks, and manage Mark versions. |
workspaces:read | Read the workspace | Read the workspace, its members and audit log. With designs:read, read /api/me. |
personalities:write | Edit brands | Create, rename and delete brands, and change a brand's Mark, profile and style. |
members:write | Invite members | Send invitations to join the workspace. |
New keys start with Read designs, Create and edit designs, Search Marks and Generate brands selected. Claim Marks is off until you choose it, because a claim makes you, the key's creator, the holder of a Mark.
Rotate a key
Keys don't expire, and a key's name and scopes can't be changed after it is made. To rotate a key, or to change what it can do, replace it:
- 1
Create the new key
Create a key with the scopes you want, named so you can tell it from the old one.
- 2
Switch your tools over
Put the new key in every place that used the old one: your MCP client, secret store or deployment settings.
- 3
Revoke the old key
When the old key's used date stops moving in the list, revoke it.
Revoke a key
In Settings › API and agents, select Revoke beside the key and confirm with Revoke key. Anything using it stops working straight away, and this can't be undone. Owners and admins of the workspace can revoke any of its keys.
A key also stops working on its own when its creator leaves the workspace, is demoted below admin, or has their account switched off. Keys a person made are revoked when they are removed from the workspace or demoted.
What a key can never do
Some things always need a person signed in to Gradiently, whatever the key's scopes:
- Create, list or revoke keys.
- Change the account: profile, email, password, sign-in sessions, or deleting it.
- Reach billing: plans, checkout, payments, AI credit top-ups, Balance and payouts. A claim or purchase that needs payment stops and asks for checkout in Gradiently.
- Give a Mark away: transfer it to someone else, release it, list it for sale, renew it or publish it.
- Move a Mark's holding or licence to the workspace. Marks a key claims are held by its creator, and any licence stays theirs.
- Change who is in the workspace or their roles, rename, transfer or delete the workspace. With
members:writeit can only send invitations. - Reach any workspace other than its own, even one its creator belongs to.
- Use Gradiently's administration.
Keep keys safe
Do
- Make one key for each tool or assistant, named after it.
- Grant the fewest scopes that do the job.
- Keep keys in a password manager, a secret store or an environment variable.
- Revoke a key the moment it might have leaked, then make a new one.
- Check the last used dates now and then, and revoke keys nobody uses.
Don't
- Commit a key to a repository or paste it into a shared configuration file.
- Put a key in a web page, a mobile app or anything that runs on someone else's device.
- Share one key between people or tools.
- Send a key by email or chat.
- Leave Claim Marks on for a key that doesn't claim.
Gradiently stores only a hash of each key and the start of it for display, so a lost key can't be shown again: revoke it and create another. If you think a key was misused, revoke it and tell us.
