API Keys

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

Service Accounts

A project's API keys belong to its service accounts, not to the members who create them. A service account is an identity that belongs to the project alone: it has a name, a role in the project, and the keys issued to it. Its keys keep working when the person who created them leaves the project, changes role or is removed — the way service accounts work on the major clouds.

A service account cannot sign in, has no password or email address, and is never listed among the project's members. It can hold the viewer, developer or admin role, never owner, and never more than the role of the member who gives it one. A project can hold up to 50 service accounts, and each can hold up to 10 keys.

Only owners and admins create, change and delete service accounts and their keys. Every member can see them, and who created each one.

GET    /v1/projects/:projectId/service-accounts
POST   /v1/projects/:projectId/service-accounts
GET    /v1/projects/:projectId/service-accounts/:id
PATCH  /v1/projects/:projectId/service-accounts/:id
DELETE /v1/projects/:projectId/service-accounts/:id

{
  "name": "CI deployer",
  "description": "Deploys from the main branch",
  "role": "developer"
}

Deleting a service account deletes every key it holds; anything using them stops working within a minute.

Create an API Key

Create a key from the control panel, under Project → API keys, with Create key on the service account it should act as — or through the API with a signed-in session:

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

Key management is never done with an API key. Creating, editing, rolling and revoking keys and service accounts 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.

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

Keys are returned once, at creation, and start with cos_pk_. 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`
`projects`	View the project and its resource groups	Rename or delete the project, set its billing email, manage resource groups
`servers`	List and view servers and SSH keys	Create and delete servers and SSH keys
`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, plans and plan quotes	Create, update, resize, deploy and delete apps
`domains`	List and view domains	Register, migrate, and manage domains
`databases`	List and view databases	Create, resize, 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
`object-storage`	List buckets and their contents	Create and delete buckets, upload and delete files
`registry`	List registries, repositories, and images	Create registries and repositories, delete images
`iam`	List access keys	Create, rotate, and delete access keys
`email`	View email domains and credentials	Create credentials, verify DNS, manage limits
`email-templates`	List and view email templates, their versions and folders	Create, update, roll back and delete templates, and manage folders
`webhooks`	List endpoints and their delivery history	Create, update, test, and delete endpoints
`integrations`	View connected git providers and other integrations	Connect, update, and disconnect integrations
`secrets`	List and view secret metadata (values are never returned)	Create, update, and delete secrets
`variables`	List and view variables (values included)	Create, update, and delete variables
`members`	List project members	Cancel invitations and transfer billing responsibility
`support`	List and view support tickets	Create and reply to tickets
`billing`	View invoices, usage, and billing history	Manage the payment method and refund the credit balance

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.

object-storage, registry, and iam replaced a single storage scope. Keys issued before the change keep working — storage still grants all three — but new keys must name the scopes they need.

What a Key Can Reach

A project key acts as its service account. It can only act on its project, and only as far as the service account's role allows — so a key on a viewer service account cannot write no matter what scopes it carries, and a key on a developer service account can deploy and manage resources but cannot change plans, secrets or variables. Scopes narrow that access; they never widen it. A request the role does not allow is refused with 403 INSUFFICIENT_ROLE; see Team Roles for what each role can do.

A key stops working if every owner of its project is suspended. Otherwise nothing that happens to the member who created it — leaving, being removed, a change of role — affects it.

A key presented against a different project — a /v1/projects/:projectId/... route, or a request that names another project, such as opening a support ticket — is refused with 403 API_KEY_WRONG_ORGANIZATION. Endpoints that are not addressed by a project answer as if the other projects did not exist: GET /v1/projects, GET /v1/domains and GET /v1/support-tickets list only the key's own project, and reading a ticket or a domain outside it returns 404 NOT_FOUND. To work on another project, issue a separate key from it.

Some actions are never available to a key, whatever its scopes: inviting, removing and changing the role of a member, accepting an invitation, managing API keys, service accounts or access tokens, and signing or ending a service agreement. They have to be taken by a person signed in to the control panel, and a request made with a key is refused.

Some more need a person at the other end, so a project key is refused with 403 SERVICE_ACCOUNT_NOT_ALLOWED: creating a project, buying a domain, connecting an integration that asks you to authorise it, opening, replying to or updating a support ticket, and transferring billing responsibility. A service account is never the project's biller either, so changing the payment method or refunding the credit balance — which only the biller may do — is refused too. Use the control panel or a personal access token for these.

Personal Access Tokens

A personal access token is a key that belongs to you rather than to one project. Create one under Account → Access tokens. Tokens start with cos_pat_ and are sent exactly like a project key, as a bearer token or in docker login.

A token acts as you in every project you are a member of, with your role in each, and only within the permissions you give it — the same scopes as a project key. GET /v1/projects lists all of those projects. Because a token is not tied to one project, tools need the project named on each call: --project or COSMONER_PROJECT_ID for the CLI, and project_id for the Terraform provider.

When you create a token you choose how long it lasts: 7, 30, 90 or 365 days, or no expiration. An expired token is refused like a revoked one. Delete a token from the same page and it stops working within a minute.

Prefer a project key for CI and anything shared with a team. A project key can only ever reach its own project, so a leaked one is contained to it; a leaked personal token reaches everything you can.

Tokens are created and deleted only in the control panel. There is no API for it, and a token cannot be used to create or list other tokens.

List API Keys

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

Every member sees every key bound to the project, with the service account it acts as and the member who issued it. Key values are never returned — only the leading characters, enough to tell two keys apart.

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"]
  }
}

Roll an API Key

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

Issues a replacement key with the same name, permissions, project and service account, then revokes the old one. Use it when a key may have been exposed, or on a schedule. The replacement has a new id, and its value is returned once in the response:

{
  "success": true,
  "data": {
    "id": "key_...",
    "name": "CI/CD Key",
    "key": "cos_pk_...",
    "serviceAccountId": "..."
  }
}

The old key stops working, so update anything using it before rolling — or, to rotate without downtime, create the replacement first, deploy it, and only then revoke the old one.

Revoke an API Key

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

Or delete the key from the list under Project → API keys in the control panel. It stops working within a minute, and anything still using it starts receiving 401 UNAUTHORIZED. Owners and admins can revoke any key in their project, whoever issued it.

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.

A personal access token works here too, and can push to or pull from the registries of any project you are a member of. A project key reaches only its own project's registries.

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.

Signing In With the CLI

cosmoner login does not create an API key. It opens a page in your browser where you check that the code matches the one in your terminal and approve. The CLI is then signed in to your account, the way your browser is: it reaches every project you are a member of, and you pick the project per command with --project or cosmoner use.

It acts as you. It can do what your role allows in each project, so a project where you are a viewer stays read-only. Inviting or removing members, creating API keys, billing and your account settings stay in the control panel.

A login stays signed in while you use it, and ends after 7 days without use or 30 days after you approved it, whichever comes first. Only approve a login you started yourself. Each machine is listed under Account → Security, where you can sign it out; cosmoner logout does the same from the machine itself.

In CI, use a project key in the COSMONER_API_KEY environment variable. It is bound to one project, and always takes priority over a login saved on the machine.

On this page