---
title: "Mint a one-use grant to reveal a secret"
method: POST
path: "/v1/instances/{id}/app/secrets/{item}/reveal-grants"
tags: ["public", "apps"]
---

# Mint a one-use grant to reveal a secret

`POST /v1/instances/{id}/app/secrets/{item}/reveal-grants`

## Request

- Base URL: `https://api.vozora.io`
- URL: `https://api.vozora.io/v1/instances/{id}/app/secrets/{item}/reveal-grants`
- Auth: API key in header `Authorization`

Step one of two. Needs apps:secrets, which does not imply apps:read — mint both if the client also lists items. The grant is single-use, short-lived, and bound to the key that minted it — another key or a browser session cannot consume it, and a revoked key is refused even if it already holds a grant token. A recovery-critical value cannot be revealed with a key at all; the dashboard is the only path, because acknowledging that you saved it is something only a person can do.

## Path parameters

- `id` string, required
- `item` string, required

## Request body

- SecretsIssueGrantRequestBody
  - `acknowledge_unrecoverable` boolean: AcknowledgeUnrecoverable is §22.3's explicit acknowledgement that Vozora cannot recover a recovery-critical secret after erasure. It is REQUIRED for that class and ignored for others.

## Response `201`

Created

- SecretsGrantResponse
  - `acknowledgement_recorded` boolean
  - `classification` string
  - `expires_at` string
  - `grant` string
  - `item` string
  - `revision` integer
  - `service_id` string

## Other responses

- `400`: reveal_acknowledgement_required
- `401`: invalid or missing API key
- `403`: the key lacks apps:secrets, or the secret is machine-only
- `404`: no such instance or item
- `422`: recovery_critical_needs_session
- `429`: reveal_rate_limited
- `503`: reveal_unavailable

---

[API](https://skmtc.dev/vozora/apis/vozora-api.md) · [All operations](https://skmtc.dev/vozora/apis/vozora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vozora/apis/vozora-api/revisions/56f15734fc5a?raw)