API Keys

API keys let you access the Cosmoner API programmatically without a browser session. Use them for CI/CD pipelines, scripts, and integrations.

Create an API Key

Keys belong to a project. Create one from the control panel, under Project → API keys → Create key, or through the API with a signed-in session:

POST /v1/projects/:projectId/api-keys

Key management is the one thing an API key cannot do. Creating, editing, rolling and revoking keys all require a browser session, so a key can never mint another key — a leaked credential cannot quietly issue itself a replacement with wider scopes or outlive the revocation of the original.

{
  "name": "CI/CD Key",
  "permissions": {
    "apps": ["read", "write"],
    "servers": ["read"]
  }
}

Keys are returned once, at creation, and start with db_. There is no way to read an existing key's value back afterwards — if you lose it, create a replacement and revoke the old one.

Permission Scopes

permissions is an object: each key is a resource, each value is the list of actions the key may perform on it. Actions are read and write.

Resource	`read`	`write`
`servers`	List and view servers	Create and delete servers
`hosting`	List and view hosted websites, their databases and domains	Create, change and delete websites, databases and domains
`apps`	List and view apps, logs, metrics	Create, update, and delete apps
`domains`	List and view domains	Register, migrate, and manage domains
`databases`	List and view databases	Create, update, and delete databases
`redis`	List and view Redis instances and browse their keys	Create, update, and delete Redis instances, edit keys, and run console commands
`storage`	List buckets and registries	Create and delete storage resources
`email`	View email domains and credentials	Create credentials, verify DNS, manage limits
`secrets`	List and view secret metadata	Create, update, and delete secrets
`variables`	List and view variables (values included)	Create, update, and delete variables
`webhooks`	List and view webhook endpoints	Create, update, and delete endpoints
`integrations`	View connected integrations	Connect, update, and disconnect integrations
`members`	List project members	Invite, remove, and update members
`support`	List and view support tickets	Create and reply to tickets

A key only carries the actions you list. Omitting permissions — or passing an empty object — does not grant full access: the key ends up with no scopes, and every scoped route answers 403 INSUFFICIENT_SCOPE.

The permissions grid in the control panel currently covers servers, hosting, apps, domains, databases, redis, storage, email, webhooks and members. To grant secrets, variables, integrations or support, set them on the key through POST /v1/projects/:projectId/api-keys or PATCH /v1/projects/:projectId/api-keys/:id.

A key is bound to one project and to the user who created it. It can only act on that project, and only as far as that user's role in it allows — so a key made by a viewer cannot write no matter what scopes it carries, and losing the membership takes the key's access with it. Scopes narrow that access; they never widen it.

Pointing a key at another project is not possible: issue a separate key from that project instead.

Update an API Key

PATCH /v1/projects/:projectId/api-keys/:id

Sending permissions replaces the key's scopes wholesale — it is not merged with what the key already had. Send the complete set you want the key to end up with.

{
  "name": "Updated Name",
  "permissions": {
    "apps": ["read"]
  }
}

Revoke an API Key

Revoking is done from the control panel, under Project → API keys — delete the key from the list. It stops working within a minute of being deleted, and any pipeline still using it starts receiving 401 UNAUTHORIZED.

Project owners and admins see every key pointing at their project, including ones created by other members, and can revoke any of them.

To rotate a key without downtime, create the replacement first, deploy it, and only then revoke the old one.

Using API Keys

Include the API key in the Authorization header:

Authorization: Bearer <your-api-key>

Docker Registry Authentication

API keys also work for authenticating docker push and docker pull against Cosmoner's container registry:

docker login registry.cosmoner.com -u _token -p <your-api-key>
docker push registry.cosmoner.com/<org>/<repo>:<tag>

The username is ignored — _token is a placeholder saying "this is not an account name", and any value works. The API key goes in the password field, and it is the same key you use as a bearer token above. There is no separate key id and secret.

The key needs the registry scope for this, the same as for any other route: registry:read to pull and registry:write to push. A key without it is refused at docker login, so a missing scope shows up before you have built anything rather than at the end of a push.

Keys Created by the CLI

Running cosmoner login opens a page in your browser where you choose the project the CLI should work in. Approving it adds a key named CLI – <your computer's name> to that project's API keys. It carries only the scopes the CLI needs, is shown on the approval page before it is issued, and expires after 90 days — run cosmoner login again to replace it.

Check that the code on the page matches the one in your terminal, and only approve a login you started yourself. cosmoner logout removes the key, and you can also revoke it here like any other key. In CI, keep using a key you created yourself in the COSMONER_API_KEY environment variable.