> ## Documentation Index > Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get a docker login credential > Mints the short-lived password `docker login` consumes. A POST rather than a GET because the response is a bearer secret: a GET would land in browser history, proxy access logs, and any intermediary that records URLs. The credential identifies the principal and nothing more. It names no repository and grants no access — the docker daemon exchanges it at `/v2/token` for per-repository bearer tokens, and every authorization decision is made there, against the policies as they stand at that moment. Requires `registry:GetAuthorizationToken`. That is a separate permission from any repository action: a principal may be allowed to pull through this API without being allowed to hand a docker daemon a credential. ## OpenAPI ````yaml /api-reference/specs/registry.yaml post /v1/authorization-token openapi: 3.0.3 info: title: Basaltic Registry API version: 1.0.0 description: | Private container image registries, backed by Ceph. **This spec documents the control plane, not the pull path.** The registry serves two protocols on one host. Everything below is the `/v1` REST surface — repositories, images, lifecycle policies, resource policies — authenticated with a request signature or a console session, like every other Basaltic API. Separately, `/v2` implements the [OCI Distribution Specification](https://github.com/opencontainers/distribution-spec) v1.1, which is what `docker`, `podman`, `buildah`, `crane`, `skopeo`, and every Kubernetes node's container runtime speak. That surface is not described here because it is not ours to describe: its paths, status codes, headers, and error codes are fixed by the spec, and a client that finds anything else fails. **Getting a docker credential.** `POST /v1/authorization-token` returns a short-lived password. Feed it to `docker login`; the daemon then exchanges it at `/v2/token` for per-repository bearer tokens on its own, which is where the actual authorization decision is made. The login credential carries no authority of its own — revoking a policy takes effect within one bearer token's lifetime (five minutes) rather than at the end of a twelve-hour login. ``` basaltic registry get-login-password --region sa-saopaulo-1 \ | docker login --username basaltic --password-stdin registry.sa-saopaulo-1.basaltic.sh docker push registry.sa-saopaulo-1.basaltic.sh/my-account/api:v1 ``` **The account handle is part of the image reference.** A region serves one registry host, so an image lives at `registry..//:`. That first path component is the only thing separating two tenants' `api` repositories, which is why every repository response includes a ready-made `uri` rather than leaving clients to assemble one. **Everything except a tag is immutable.** A blob is named by the sha256 of its bytes and a manifest by the sha256 of its own JSON, so pushing the same content twice is a no-op the client detects before it uploads a byte. A tag is the one mutable pointer — and a repository may forbid even that, with `tag_mutability: immutable`, so a deployed digest cannot be swapped under a running fleet. **Deleting by digest and deleting by tag are different.** Removing a digest removes the manifest and every tag pointing at it. Removing a tag leaves the manifest in place, untagged: another tag may still name it, and `docker rmi` of one tag must not destroy an image someone else is pulling by another. Untagged manifests are what the `untagged` lifecycle rule exists to sweep. **Layers are shared and counted once.** Blobs are deduplicated across every repository in an account, so a repository's `size_bytes` is the sum of the distinct blobs its manifests reference — not the sum of its images' sizes, which would count every shared base layer once per image. Deleting an image does not immediately free space: whether a layer is still needed is a question about every other repository in the account, and the answer comes from a background sweep. **Sharing a repository.** A repository is private to its account until you attach a resource policy. `PUT /v1/repositories/{id}/policy` is how another account — or, with principal `*`, the public — is granted pull access. Cross-account access requires BOTH the resource policy and the caller's own IAM policy to allow it, so one tenant cannot grant another tenant's employee more than that employee's organization permits. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://registry.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] tags: - name: Authorization description: The credential `docker login` consumes - name: Repositories description: Repository lifecycle and settings, and the images and tags in one - name: Policies description: Resource policies and lifecycle policies - name: Encryption description: At-rest encryption of layer bytes - name: Pull-through cache description: Mirroring an upstream registry's images into a namespace of your own paths: /v1/authorization-token: post: tags: - Authorization summary: Get a docker login credential description: | Mints the short-lived password `docker login` consumes. A POST rather than a GET because the response is a bearer secret: a GET would land in browser history, proxy access logs, and any intermediary that records URLs. The credential identifies the principal and nothing more. It names no repository and grants no access — the docker daemon exchanges it at `/v2/token` for per-repository bearer tokens, and every authorization decision is made there, against the policies as they stand at that moment. Requires `registry:GetAuthorizationToken`. That is a separate permission from any repository action: a principal may be allowed to pull through this API without being allowed to hand a docker daemon a credential. operationId: getAuthorizationToken responses: '200': description: A docker credential valid for 12 hours. content: application/json: schema: $ref: '#/components/schemas/AuthorizationTokenResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: AuthorizationTokenResponse: type: object properties: authorization_data: type: object properties: authorization_token: type: string description: | `base64(":")` — the single opaque blob ECR-shaped tooling expects. username: type: string description: | Fixed, and ignored on the way in: the token identifies the principal. Present so `docker login -u` has something to pass. example: basaltic password: type: string description: The credential itself, for `docker login --password-stdin`. endpoint: type: string example: registry.sa-saopaulo-1.basaltic.sh expires_at: type: string format: date-time required: - authorization_token - username - password - endpoint - expires_at required: - authorization_data Error: type: object required: - error properties: error: type: object required: - code - message - request_id properties: code: type: string description: Error code identifying the type of error example: INVALID_INPUT message: type: string description: Human-readable error message example: Invalid request parameters request_id: type: string format: uuid description: Request ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 responses: Unauthorized: description: Authentication required or token invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: UNAUTHORIZED message: Authentication required request_id: 550e8400-e29b-41d4-a716-446655440000 Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ACCESS_DENIED message: You don't have permission to perform this action request_id: 550e8400-e29b-41d4-a716-446655440000 securitySchemes: SignatureAuth: type: apiKey in: header name: Authorization description: > Request signing with an access key issued to a service account. An HMAC-SHA256 over a canonical form of the request, close to AWS SigV4. The `basaltic` CLI signs for you. Send `Authorization`, `X-Date` (UTC, `YYYYMMDDTHHMMSSZ`) and `X-Nonce` (random per request); add `X-Content-Sha256` to bind a body, and `X-Amz-Security-Token` when using temporary credentials. ``` Authorization: BASALTIC-HMAC-SHA256 Credential=///basaltic/basaltic_request, SignedHeaders=host;x-date;x-nonce, Signature= ``` `` is the region code you are calling, or `global` for the global services. A signature is valid for 5 minutes from `X-Date`, and mutating requests are replay-guarded on the nonce. **Full signing procedure, including a working implementation:** https://docs.basaltic.sh/authentication ## Rate limits There is no global request budget. A limit applies only where an operation documents a `429`, and that operation says what it counts. Those responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and, on a `429`, `Retry-After` — read them rather than hard-coding a number. Retrying before `Retry-After` is refused and extends the window. Everything else is bounded by quota, not by request rate. ````