> ## 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. # Schedule deletion (soft delete with recovery window) ## OpenAPI ````yaml /api-reference/specs/secrets.yaml delete /v1/secrets/{secret_id} openapi: 3.0.3 info: title: Basaltic Secrets API version: 1.0.0 description: | Versioned application secrets with KMS-backed envelope encryption. Secrets are regional. The value of every version is encrypted at rest under a KMS key — only opaque ciphertext is persisted. By default a secret uses the platform-managed key; pass kms_key_id on CreateSecret to bind it to one of your own KMS keys instead (the key is fixed for the secret's life, and every version is encrypted under it). Each PutSecretValue allocates a new monotonically-increasing version number and flips is_current on the previous row; older versions remain readable by explicit version query. Soft delete: DeleteSecret moves the secret into a recovery window (default 7 days, configurable 1-30). RestoreSecret exits the window. The hard-purge sweeper removes the row + every version once now() >= scheduled_purge_at. Values move on the wire as base64 to survive arbitrary binary payloads (max 64 KiB to mirror AWS Secrets Manager). contact: name: Basaltic Support email: ping@basaltic.sh license: name: Proprietary url: https://basaltic.sh/terms servers: - url: https://secrets.{region}.basaltic.sh description: Regional API endpoint variables: region: default: sa-saopaulo-1 description: Region code security: - SignatureAuth: [] tags: - name: Secrets description: Secret metadata + value lifecycle paths: /v1/secrets/{secret_id}: parameters: - $ref: '#/components/parameters/SecretId' delete: tags: - Secrets summary: Schedule deletion (soft delete with recovery window) operationId: deleteSecret requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/DeleteSecretRequest' responses: '200': description: Secret scheduled for purge. content: application/json: schema: $ref: '#/components/schemas/SecretResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: SecretId: name: secret_id in: path required: true schema: type: string format: uuid example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d schemas: DeleteSecretRequest: type: object properties: recovery_window_seconds: type: integer description: Override the secret's default window. Omit to keep it. minimum: 86400 maximum: 2592000 example: 1209600 SecretResponse: type: object required: - secret properties: secret: $ref: '#/components/schemas/Secret' Secret: type: object required: - id - name - crn - managed - recovery_window_seconds - created_at - updated_at properties: id: type: string format: uuid example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d name: type: string example: prod/api/stripe-key description: type: string example: Stripe live secret key for the payments service tags: $ref: '#/components/schemas/Tags' crn: type: string example: crn:secrets:sa-saopaulo-1:my-account:secret/prod/api/stripe-key kms_key_id: type: string format: uuid nullable: true description: >- Customer-managed KMS key the secret is encrypted under. Null (omitted) when encrypted with the platform-managed default key. example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 managed: type: boolean readOnly: true description: >- True when a platform service generated this value and reads it back to act on. You can read and delete a managed secret, but UpdateSecret and PutSecretValue answer 403 SECRET_PLATFORM_MANAGED. example: false deleted_at: type: string format: date-time nullable: true example: '2026-01-20T14:05:00Z' scheduled_purge_at: type: string format: date-time nullable: true example: '2026-01-27T14:05:00Z' recovery_window_seconds: type: integer example: 604800 current_version: type: integer description: 0 if no version exists yet. example: 3 created_at: type: string format: date-time example: '2026-01-15T09:30:00Z' updated_at: type: string format: date-time example: '2026-01-18T11:45:00Z' 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 responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_INPUT message: Invalid request parameters request_id: 550e8400-e29b-41d4-a716-446655440000 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 NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: NOT_FOUND message: Resource not found 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. ````