---
title: "Reveal a secret value once"
method: POST
path: "/v1/instances/{id}/app/secrets/{item}/reveal"
tags: ["public", "apps"]
---

# Reveal a secret value once

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

## Request

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

Step two of two. Atomically consumes the grant and returns exactly one value; the grant is burned whether or not the reveal succeeds. The calling key and the bound revision are re-read and compared at consume time, so a different key, a rotation, a reinstall supersession or a termination invalidates an outstanding grant. A REVOKED key is refused earlier still, by the credential check every request passes through. Every reveal is audited with the key's id. The response is Cache-Control no-store, private.

## Path parameters

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

## Request body

- SecretsRevealRequestBody
  - `grant` string

## Response `200`

OK

- SecretsRevealResponse
  - `classification` string
  - `item` string
  - `purpose` string
  - `revealed_at` string
  - `revision` integer
  - `save_acknowledgement_challenge` string
  - `save_acknowledgement_expires_at` string
  - `service_id` string
  - `value` string

## Other responses

- `400`: reveal_grant_malformed
- `401`: invalid or missing API key
- `403`: the key lacks apps:secrets, or the grant is invalid
- `404`: no such instance or item
- `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)