Image access API
Create, rotate, inspect, and remove exact-repository pull access.
Operations
| Method | Path | Purpose |
|---|---|---|
| GET | /api/registries | Read account-owned access metadata and linked services |
| POST | /api/registries | Save access for a private repository |
| PUT | /api/registries/{id} | Replace credentials at the current revision |
| DELETE | /api/registries/{id} | Remove access after linked services are paused |
All operations use normal Oiy account authentication. Creating and rotating require verified email; these routes are not restricted to interactive Firebase sign-in. Mutations require Idempotency-Key.
Create body
The strict specification contains:
| Field | Requirement |
|---|---|
name | Trimmed display name, 1–64 characters |
repository | Exact fully qualified repository, 3–512 characters, without scheme, tag, or digest |
username | Write-only, 1–512 characters; no colon, line break, or null character |
password | Write-only pull credential, 1–8,192 characters |
Use a repository-scoped pull-only credential. Supply secret values from a secure local environment when building the HTTPS request. They are not service environment variables.
A successful creation returns a bare metadata object with HTTP 201: id, name, repository, revision, createdAt, and updatedAt. Timestamps are Unix milliseconds. No username or password is returned.
Read metadata
GET /api/registries returns { "registries": [...] }. Each entry extends the metadata with services, listing linked service ID, name, status, and allocation state. The list never exposes secret material.
Rotate
PUT /api/registries/{id} accepts a wrapper containing the current revision and a complete spec. Include the unchanged repository, the desired display name, and replacement username/password values.
The response is a bare metadata object with HTTP 200. Rotation affects future admitted launches; it neither stops existing work nor rewrites already-admitted credential snapshots.
Remove
DELETE /api/registries/{id} includes a JSON body with revision. Every linked service must be sleeping and unallocated. The response is { "id": "REGISTRY_ID", "deleted": true }.
Deletion removes saved access, not image contents or workspace files. Bound services must restore access or change images before launching again; they do not silently fall back to anonymous pulls.
Common rejections
| Code | Meaning |
|---|---|
EMAIL_NOT_VERIFIED | Verify the account before saving or rotating. |
REGISTRY_SCOPE | The repository cannot be changed in-place. |
REGISTRY_EXISTS | This exact repository already has an entry. |
REGISTRY_LIMIT | The account already has 20 entries. |
REVISION_CHANGED | Read the latest metadata before another mutation. |
REGISTRY_IN_USE | Wait for confirmed pause of all linked services. |
REGISTRY_ACCESS_REQUIRED | Restore access or choose another image before a bound service starts. |
See Private container images for the complete user workflow.