Registry tokens API endpoints

View as Markdown Open in Claude Open in ChatGPT

Registry tokens are the credentials docker, your CI and your Kubernetes clusters use to push and pull images from the Cloider container registry. A token reaches every project of the account or only the ones you choose, can be pull only, and can expire. These endpoints list, create, change and delete them. The dashboard shows them under Access Control, Registry Tokens.

All paths are relative to https://cloider.com/api. See Registry tokens for using a token with docker login and Kubernetes.

At a glance

Method	Path	Access
GET	`/registry/tokens`	Read
POST	`/registry/tokens`	Write
PUT	`/registry/tokens/:hashed_id`	Write
DELETE	`/registry/tokens/:hashed_id`	Write

An account can have up to 50 registry tokens.

A registry login is a username and a password:

The username is the account's registry username (the username field), the same for every token of the account. It never changes.
The password is the token's secret, returned once when the token is created. A login can reach what that token allows, and nothing more.

echo "$REGISTRY_SECRET" | docker login registry.cloider.com -u acme --password-stdin
docker push registry.cloider.com/acme/api:1.4.2

The registry token object

{
  "hashed_id": "t3n8q",
  "label": "ci-deploy",
  "username": "acme",
  "all_projects": false,
  "projects": ["r4c8z"],
  "read_only": false,
  "expires_at": "2027-10-20T09:31:12.551203Z",
  "status": "Ready",
  "created_at": "2026-10-20T09:31:12.551203Z"
}

Field	Type	Description
`hashed_id`	string	The token's id in the API
`label`	string	The name you gave it
`username`	string	The username to log in with. Some older tokens show a longer username of their own: log in with it exactly as shown
`all_projects`	boolean	`true` when the token reaches every project of the account, including projects created later
`projects`	string list	When `all_projects` is `false`, the `hashed_id`s of the projects it reaches
`read_only`	boolean	`true` for a pull only token
`expires_at`	string or null	When the token stops working, or `null` for never
`status`	string	`Creating`, `Ready`, `Terminating` or `Failed`
`created_at`	string	When the token was created

The secret is never part of this object.

List registry tokens

GET /registry/tokens

Returns the account's registry tokens, newest first.

Access: any token.

curl https://cloider.com/api/registry/tokens \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

The response is a list of registry token objects.

Create a registry token

POST /registry/tokens

Creates a registry token and returns its secret. The secret is shown only in this response. Store it right away, for example as a CI secret or a Kubernetes pull secret.

Access: Read & Write token.

Field	Type	Required	Description
`label`	string	Yes	A name for the token, 1 to 64 characters
`all_projects`	boolean	No	`true` to reach every project of the account. Default `false`
`projects`	string list	When `all_projects` is `false`	The `hashed_id`s of the projects the token reaches, at least one
`read_only`	boolean	No	`true` for pull only. Default `false` (pull and push)
`expires_in_days`	integer	No	Days until the token stops working, 1 to 3650. `0` or left out for never

At least one of the projects the token reaches must be Ready.

curl -X POST https://cloider.com/api/registry/tokens \
  -H "Authorization: Bearer $CLOIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-deploy", "projects": ["r4c8z"], "expires_in_days": 365}'

Response
{
  "token": {
    "hashed_id": "t3n8q",
    "label": "ci-deploy",
    "username": "acme",
    "all_projects": false,
    "projects": ["r4c8z"],
    "read_only": false,
    "expires_at": "2027-10-20T09:31:12.551203Z",
    "status": "Ready",
    "created_at": "2026-10-20T09:31:12.551203Z"
  },
  "secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

RESPONSE=$(curl -s -X POST https://cloider.com/api/registry/tokens \
  -H "Authorization: Bearer $CLOIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "prod-cluster", "projects": ["r4c8z"], "read_only": true}')

kubectl create secret docker-registry cloider-registry \
  --docker-server=registry.cloider.com \
  --docker-username="$(jq -r .token.username <<<"$RESPONSE")" \
  --docker-password="$(jq -r .secret <<<"$RESPONSE")"

Errors

Status	Field	Message
`400`	`label`	`Name must not be empty`, `Name must not exceed 64 characters`
`400`	`projects`	`Choose at least one project`, `One of the projects doesn't exist any more, reload and try again`, `Choose a project that is ready, or create one first`
`400`	`expires_in_days`	`Expiry must be between 1 and 3650 days, or never`
`400`	`_`	`An account can have up to 50 registry tokens, delete one you no longer use!`
`400`	`_`	`Your account is suspended. Upgrade to a paid plan to continue using our services.`
`400`	`_`	`Operation failed, Couldn't create the registry token!`
`403`	`_`	`This API token is read only!`, `You have read-only access to this account, you can not create registry tokens!`

Change a registry token

PUT /registry/tokens/:hashed_id

Changes a token's label, the projects it reaches and whether it is pull only. The secret, the username and the expiry stay the same. Send the full form: fields you leave out take their defaults.

Access: Read & Write token. The registry token must be Ready.

Field	Type	Required	Description
`label`	string	Yes	1 to 64 characters
`all_projects`	boolean	No	`true` for every project
`projects`	string list	When `all_projects` is `false`	The project ids
`read_only`	boolean	No	`true` for pull only

curl -X PUT https://cloider.com/api/registry/tokens/t3n8q \
  -H "Authorization: Bearer $CLOIDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-deploy", "all_projects": true, "read_only": false}'

The response is the updated list of registry tokens. Besides the validation errors of create, it can answer 400 with The registry token must be ready to be changed. or Couldn't change the registry token, try again in a moment!, in which case the token keeps its previous settings. The expiry can't be changed: create a new token instead.

Delete a registry token

DELETE /registry/tokens/:hashed_id

Deletes a registry token. Logins with its secret stop working.

Access: Read & Write token.

curl -X DELETE https://cloider.com/api/registry/tokens/t3n8q \
  -H "Authorization: Bearer $CLOIDER_TOKEN"

The response is the updated list of registry tokens.

Status	Message
`400`	`The registry token is busy, try again in a moment!`
`400`	`Couldn't delete the registry token, try again in a moment!`
`403`	`This API token is read only!`, `You have read-only access to this account, you can not delete registry tokens!`
`404`	`Not Found` (plain text)

Registry tokens in the dashboard, CLI and Terraform
Use with Kubernetes and CI/CD
cloider_registry_token Terraform resource

At a glance​

How a registry login works​

The registry token object​

List registry tokens​

Create a registry token​

Errors​

Change a registry token​

Delete a registry token​

Related​