> ## 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. # List KMS keys > List KMS keys owned by the requesting account, newest-first. Keyset-paginated by key id (UUIDv7 sorts by creation time) — pass the last id from the previous page as `marker` to fetch the next. ## OpenAPI ````yaml /api-reference/specs/kms.yaml get /v1/keys openapi: 3.0.3 info: title: Basaltic KMS API version: 1.0.0 description: | Customer-managed encryption keys. Encrypt and decrypt directly, or let another service — secrets, storage, images — wrap its data keys with one of yours. contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://kms.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] paths: /v1/keys: get: tags: - KMS summary: List KMS keys description: | List KMS keys owned by the requesting account, newest-first. Keyset-paginated by key id (UUIDv7 sorts by creation time) — pass the last id from the previous page as `marker` to fetch the next. operationId: listKeys parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 500 default: 50 example: 50 - name: marker in: query schema: type: string format: uuid example: 7c9e2f4a-1d83-4b6e-9a2c-5f8b0d3e6a17 description: Resume token — the last key id from the previous page. - name: state in: query schema: $ref: '#/components/schemas/KeyState' description: Optional state filter (enabled / disabled / pending_deletion). - name: name in: query schema: type: string example: prod-master description: Optional substring filter on key name. responses: '200': description: List of keys content: application/json: schema: $ref: '#/components/schemas/KeyListResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' security: - SignatureAuth: [] components: schemas: KeyState: type: string enum: - enabled - disabled - pending_deletion description: | Lifecycle state: - enabled: usable for spec/usage operations - disabled: exists; refuses crypto ops; can be re-enabled - pending_deletion: scheduled for hard delete at deletion_scheduled_at; cancellable until then example: enabled KeyListResponse: type: object properties: keys: type: array items: $ref: '#/components/schemas/Key' meta: $ref: '#/components/schemas/PaginationMeta' Key: type: object required: - id - crn - name - key_spec - key_usage - state - tags - created_at - updated_at properties: id: type: string format: uuid readOnly: true example: 3f8a1c2e-9b47-4d6a-bc11-0e2f5a7d9c41 crn: type: string readOnly: true example: crn:kms:sa-saopaulo-1:my-account:key/prod-master name: type: string example: prod-master description: type: string example: Master KEK for the production data plane tags: $ref: '#/components/schemas/Tags' key_spec: $ref: '#/components/schemas/KeySpec' key_usage: $ref: '#/components/schemas/KeyUsage' state: $ref: '#/components/schemas/KeyState' system: type: boolean readOnly: true example: true description: | Present and true on platform-owned envelope keys (credential master, JWT signer, …), which are visible but not yours to operate on. Omitted on customer keys. Console and CLI read it to hide the destructive actions. deletion_scheduled_at: type: string format: date-time nullable: true example: '2026-01-22T09:30:00Z' description: | Set only while state=pending_deletion. The key (and its cryptographic material) is hard-deleted once now() reaches this timestamp; CancelKeyDeletion before then returns the key to state=disabled. created_at: type: string format: date-time readOnly: true example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time readOnly: true example: '2026-01-15T09:30:00Z' PaginationMeta: type: object properties: total: type: integer description: Total number of items example: 150 limit: type: integer description: Number of items per page example: 20 marker: type: string description: >- Opaque cursor for the next page. Pass it back as the `marker` query parameter; treat it as a token, not a value to parse. example: 550e8400-e29b-41d4-a716-446655440000 has_more: type: boolean description: Whether there are more items example: true 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 Tags: type: object additionalProperties: type: string example: environment: production team: backend KeySpec: type: string enum: - aes-256 - rsa-2048 - rsa-4096 - ecdsa-p256 description: | Cryptographic spec. Determines which mechanisms apply: - aes-256: symmetric AEAD (AES-GCM) - rsa-2048: asymmetric; OAEP-SHA256 encrypt + PSS-SHA256 sign - rsa-4096: same as rsa-2048 - ecdsa-p256: asymmetric; SHA-256 sign/verify (no encrypt) example: aes-256 KeyUsage: type: string enum: - encrypt_decrypt - sign_verify description: | Operation set the key is pinned to at create time. Even when the spec supports both (RSA), one usage must be chosen — the service refuses operations from the other set. example: encrypt_decrypt 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 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INTERNAL_ERROR message: An internal error occurred 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. ````