> ## Documentation Index > Fetch the complete documentation index at: https://docs.qanapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Export a key's private material > Requires `kms:export` on the key, and a key marked `private_material_retrievable` whose export window has not closed. Returns the private half wrapped as an RFC 7516 JWE under the named RSA wrap key, so it is readable only by whoever holds that key's private half. Each export increments `export_count`, which is on the audit trail. ## OpenAPI ````yaml /openapi/stand-alone/v3.yaml post /api/v3/kms/{uuid}/export openapi: 3.1.0 info: title: Qanapi Standalone API version: 3.0.0 summary: Single-tenant encryption, key management, classification and audit service. description: > A standalone cryptographic service. Callers hand it data and it returns ciphertext, or hand it ciphertext and it returns data, with every operation authorised by policy and recorded on a tamper-evident audit trail. ## Authentication Two credentials reach the same principal: - **API key** in `X-Qanapi-Authorization`, for machine callers. A key reaches only the configurations it is linked to. - **User bearer token** in `Authorization`, from `POST /api/v3/auth/login`, for a person working through a console. An API key outranks a bearer token when a request carries both, because a key names a narrower credential than the user that owns it. ## Request bodies Endpoints that take a JSON body require `Content-Type: application/json`. The two encryption endpoints are the exception: in whole-body mode they accept any bytes at all, whatever the content type says. ## Errors Every error body carries `message`, which is human readable, and `error`, a stable machine readable code that clients can branch on. Validation failures additionally carry an `errors` object keyed by the field each message concerns; a failure with no single field to blame is filed under `request`. ## Rate limiting Every response carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`. The window is per node and keyed on the client address, so a cluster of n nodes admits n times the configured figure. `POST /api/v3/auth/login` is limited separately and more strictly, ten a minute against sixty, because it needs no credential to reach and each attempt costs a full password verification. A successful login clears that budget, so the stricter limit falls on failed attempts rather than on legitimate sign-ins. ## Correlation Send `X-Request-Id` to tie a request to your own trace. The value is preserved on the audit record and echoed on the response, provided it is at most 64 characters of letters, digits, `-`, `_`, `.` or `:`; anything else is replaced with a generated id. Omit the header and one is generated for you. ## End-to-end encrypted requests and responses Any endpoint accepts a request body wrapped as an RFC 7516 JWE, so the payload is unreadable by anything between your client and this service, including the reverse proxy that terminates TLS. Wrap the JSON body to the key from `GET /api/v3/qanapi-public-key` and send it with `Content-Type: application/jose`; `application/jwt` and `application/jose+json` are accepted too, and a body that is plainly a compact JWE is recognised even without one of those content types. Where the installation requires it, the wrapped payload must carry `iat`, `exp` and `jti` claims, which also make each payload single-use. To have the **response** wrapped in turn, send `X-Qanapi-Wrap-With-Key-Id` naming an RSA key held in this service's KMS that you hold the private half of. The response then arrives as a compact JWE with `Content-Type: application/jose`. The header spelling `wrap_with_key_id` is accepted as well. The wrapping key is resolved with the same permission a plain key read needs, so a caller who may not read that key gets an error instead of a wrapped body. license: name: Proprietary identifier: LicenseRef-Qanapi-Commercial servers: - url: https://{host} description: A deployed instance, behind the reverse proxy that terminates TLS. variables: host: default: qanapi.example.com - url: http://localhost:8000 description: A local cluster, through its load balancer. security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: STAND Health description: > Liveness and readiness probes. Registered outside the authentication, audit and transport layers, so a load balancer polling them without credentials still gets an answer. - name: STAND Authentication description: > Logging in. There is no registration endpoint: the first administrator is created from the command line on the host, so nothing reachable over the network can claim an installation that has no users yet. Later accounts are created through `POST /api/v3/users`. - name: STAND Users description: User accounts and their roles. - name: STAND API keys description: > Machine credentials. A key is scoped to a set of configurations and reaches nothing until it is linked to at least one. - name: STAND Configurations description: > Encryption configurations. A configuration owns a master key and is the unit of cryptographic isolation. - name: STAND Classifications description: Sensitivity labels and the clearance that reaches them. - name: STAND Policies description: Allow and deny rules binding a principal to actions on resources. - name: STAND Encryption description: > The data plane. Field-level or whole-body encryption under a configuration, optionally forwarded onward to a destination of the caller's choosing. - name: STAND KMS description: Customer-managed key lifecycle, import and export. - name: STAND Audit description: The tamper-evident record of everything the service did. - name: STAND Transport description: The service's own key pair, for end-to-end encrypted request bodies. paths: /api/v3/kms/{uuid}/export: parameters: - $ref: '#/components/parameters/KeyUuid' post: tags: - STAND KMS summary: Export a key's private material description: | Requires `kms:export` on the key, and a key marked `private_material_retrievable` whose export window has not closed. Returns the private half wrapped as an RFC 7516 JWE under the named RSA wrap key, so it is readable only by whoever holds that key's private half. Each export increments `export_count`, which is on the audit trail. operationId: exportKmsKey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ExportKmsKeyRequest' responses: '200': description: The key, with `private_key_material.jwe` present. content: application/json: schema: $ref: '#/components/schemas/KmsKey' '400': $ref: '#/components/responses/NoCredential' '401': $ref: '#/components/responses/BadCredential' '403': description: | The key is not marked exportable, its export window has closed, or the caller lacks `kms:export`. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: No such key, or `wrap_with_key_id` names no usable RSA key. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/ValidationFailed' components: parameters: KeyUuid: name: uuid in: path required: true description: The key's `key_id`. schema: type: string format: uuid schemas: ExportKmsKeyRequest: type: object required: - wrap_with_key_id properties: wrap_with_key_id: type: string format: uuid description: | An RSA key whose public half wraps the export. Whoever holds its private half is the only party that can read the result. KmsKey: allOf: - $ref: '#/components/schemas/KmsKeyBrief' - type: object required: - private_material_retrievable - usage_mask - updated_at properties: private_material_retrievable: type: boolean description: > Whether the private half may ever leave this service. Fixed at creation: it can be withdrawn later but never granted, because the guarantee made when the key was generated has to keep holding. usage_mask: type: array description: | What the key may be used for. Defaults to `["encrypt", "decrypt"]` when a key is created without one. items: type: string enum: - encrypt - decrypt - sign - verify classification_id: type: string format: uuid description: > Present when the key carries a classification. Decrypting through it then requires the matching clearance. revoke_reason: type: string description: Present only on a revoked key, and only when one was given. rotated_from: type: string format: uuid description: The key this one replaced, when it came from a rotation. export_window_expires_at: type: - string - 'null' format: date-time description: > After this, export is refused even for an exportable key. Present only on exportable keys. export_count: type: integer description: > How many times the private half has been exported. Present only on exportable keys. public_key_pem: type: string description: RSA keys only, and always safe to hand out. private_key_material: type: object description: | Present only in the response to an export, or to a create with `export_on_create`. Never returned by a plain fetch. required: - jwe properties: jwe: type: string description: > RFC 7516 compact serialisation, `RSA-OAEP-256` with `A256GCM`, wrapped to the named wrap key. updated_at: type: string format: date-time Error: type: object required: - message - error properties: message: type: string description: | Human readable. A server-side fault is described by its category and nothing more: operational detail stays in the service's own log. examples: - Unauthorized. error: type: string description: | A stable machine readable code. Branch on this rather than on `message`, which is shared between conditions that this code tells apart. examples: - InvalidApiKeyException KmsKeyBrief: type: object description: The compact form returned by the list endpoint. required: - key_id - name - external_id - type - algorithm - state - created_at properties: key_id: type: string format: uuid description: How every other KMS endpoint names this key. name: type: - string - 'null' external_id: type: - string - 'null' description: | A caller's own identifier, for reconciling against another system. type: type: string enum: - AES - RSA algorithm: type: string description: The key length, without the cipher mode. examples: - AES-256 - RSA-2048 cipher_mode: type: string enum: - gcm - cbc description: | The AES mode. Absent for an RSA key, which has none. state: $ref: '#/components/schemas/KeyState' created_at: type: string format: date-time ValidationError: allOf: - $ref: '#/components/schemas/Error' - type: object required: - errors properties: errors: type: object description: > Messages keyed by the field they concern. A failure with no single field to blame is filed under `request`. additionalProperties: type: array items: type: string examples: - type: - The type field is required. configuration_ids: - No configuration has the id `...`. KeyState: type: string enum: - active - revoked responses: NoCredential: description: | No credential was presented. Send an API key in `X-Qanapi-Authorization`, or a bearer token in `Authorization`. content: application/json: schema: $ref: '#/components/schemas/Error' BadCredential: description: A credential was presented and did not verify. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationFailed: description: | The request body or a parameter is invalid. `message` is always `Validation failed`; the specifics are in `errors`, keyed by field. content: application/json: schema: $ref: '#/components/schemas/ValidationError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Qanapi-Authorization description: | A machine credential, `qk_` followed by its secret. Only a hash of the secret is stored, so a key is displayed exactly once, when it is created or rotated. A key reaches only the configurations it is linked to. It may also be sent as `Authorization: Bearer qk_...`, which is recognised by the prefix. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | A user token from `POST /api/v3/auth/login`. The token asserts a role, but the database decides it, so a role changed or a user deleted after the token was issued takes effect immediately. A token minted before a password change is refused. ````