canonical: https://jentic.com/apis/onetimesecret.com/onetimesecret

# Onetime Secret API

Onetime Secret is a service for sharing sensitive information securely. Secrets are encrypted server-side and can be viewed once before they are destroyed, removing the long-lived attack surface of email, chat, or ticket attachments. The API supports creating user-supplied or randomly generated secrets, retrieving them via a one-time key, inspecting metadata for the sender, burning a secret before it is read, and listing recent metadata entries.

## For AI agents

Create one-time secrets, share them via short-lived links, retrieve or burn them, and inspect metadata as the sender - through the Onetime Secret API.

## Scope

Does not handle persistent secret storage, key rotation, or full secrets-vault management - use for one-time secret share, retrieve, and burn operations only.

## Capabilities

- Create a new one-time secret with user-supplied content and TTL
- Generate a random secret server-side and return its sharing key
- Retrieve a secret exactly once before it is destroyed
- Burn a secret early using its metadata key to revoke access
- Inspect sender-side metadata for previously created secrets
- List recent secret metadata for the authenticated account

## Use cases

### Sharing Credentials with Colleagues

Share API keys, database passwords, or temporary tokens with colleagues using a single-use link instead of long-lived chat or email messages. POST `/v1/share` creates a secret with the supplied content and TTL; the returned key is delivered to the recipient who reads it once before the secret is destroyed.

Example prompt: Create a one-time secret containing a temporary AWS access key with a 30-minute TTL, then return the share URL to deliver to the recipient.

### Random Token Generation

Generate a strong random secret server-side via POST `/v1/generate` when the sender does not need to choose the value themselves, such as issuing a one-time setup code. The endpoint returns both the share key for the recipient and the metadata key for sender-side inspection or revocation.

Example prompt: Generate a 32-character random secret with a 1-hour TTL and return the share key plus metadata key.

### Revoking a Secret Before Read

Cancel a previously created secret if it was sent to the wrong person or is no longer needed. POST `/v1/private/{metadata_key}/burn` destroys the secret server-side using the sender's metadata key, ensuring the recipient cannot retrieve it even if they hold the share link.

Example prompt: Burn the secret with metadata key 'mk-abc-123' before the recipient retrieves it.

### Agent-Driven Secret Sharing via Jentic

Operations agents share temporary credentials with humans or other agents through Jentic without holding the Onetime Secret basic-auth credentials directly. The agent searches for the share intent, loads the schema, and executes POST `/v1/share` with the content and TTL needed for the workflow.

Example prompt: Use Jentic search 'share onetime secret' to locate POST `/v1/share`, load the schema, and execute with the credential to share and a 15-minute TTL.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/share` | Create a one-time secret with user-supplied content |
| POST | `/v1/generate` | Generate a random one-time secret |
| POST | `/v1/secret/{secret_key}` | Retrieve a secret by its share key (single use) |
| POST | `/v1/private/{metadata_key}` | Get sender-side metadata for a created secret |
| POST | `/v1/private/{metadata_key}/burn` | Burn a secret before it has been read |
| GET | `/v1/private/recent` | List recent secret metadata for the account |
| GET | `/v1/status` | Get system status |

## Key resources

- **Secrets** — Create, retrieve, and burn one-time secrets with optional metadata
- **System** — Inspect Onetime Secret service status

## Why Jentic

- **Setup:** Wiring the Onetime Secret API by hand means setting up HTTP Basic with your username and API token and building each share, retrieve, and burn call against onetimesecret.com/api yourself. Through Jentic you install once, import the Onetime Secret API from the API Directory, store the basic-auth pair once, and your agent calls it.
- **Permission scoping:** Onetime Secret identifies each secret by a generated key in the path, but that key is issued per share rather than a resource you scope to, so you limit the agent to the operations it needs, such as sharing or generating a secret. Burning a secret or listing recent metadata are excluded unless you add those operations to the allowed set.
- **Credential handling:** Your Onetime Secret username and API token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'share a one-time secret' or 'burn a secret', and Jentic returns the matching Onetime Secret operation (POST `/v1/share` or `/v1/generate`) with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Evervault Encryption API** — Evervault provides programmatic encryption and tokenisation for sensitive data flows.
- **Stripe API** — Stripe is unrelated to secrets but commonly sits alongside in operational tooling.
- **SendGrid Email Activity** — Pair SendGrid with Onetime Secret to email recipients the secret share link.

## FAQ

### What authentication does the Onetime Secret API use?

The API uses HTTP basic authentication with a username and API token. Through Jentic the credentials live encrypted in the vault (your Jentic One instance) and the agent only ever holds a scoped reference.

### Can I revoke a Onetime Secret after creating it?

Yes. Use POST `/v1/private/{metadata_key}/burn` with the metadata key returned at creation time to destroy the secret server-side before the recipient reads it.

### Does the Onetime Secret API tell me whether a secret has been viewed?

Yes. POST `/v1/private/{metadata_key}` returns sender-side metadata that includes the read state, so callers can confirm whether the recipient has retrieved the secret.

### How do I generate a random secret instead of supplying my own?

POST `/v1/generate` creates a random secret server-side and returns both the share key for the recipient and the metadata key for the sender to use later for inspection or burning.

### What are the rate limits for the Onetime Secret API?

Rate limits are not declared in the OpenAPI spec. Consult onetimesecret.com for the current free and paid tier limits before driving heavy automated traffic.

### How do I share a credential through Jentic?

Run pip install jentic, search 'share onetime secret', then load the POST `/v1/share` schema and execute with the secret content and TTL. Jentic injects the basic-auth credentials from its vault.

### Can I limit what my agent is allowed to do with the Onetime Secret API?

Yes. Because you run Jentic One yourself, your own rules decide which Onetime Secret operations the agent may call and which credentials it may use. Since each secret is addressed by a per-share key rather than a resource you can scope to, you control access at the operation level: allow only what the workflow needs, such as creating a secret with POST `/v1/share` or generating one with POST `/v1/generate.` Operations like burning a secret with POST `/v1/private/{metadata_key}/burn` or listing recent metadata with GET `/v1/private/recent` stay excluded unless you add them to the allowed set.