Skip to content

You're viewing the prerelease documentation siteContent here is for testing and may differ from the live docs.

Go to live docs

API and client libraries

Everything the web app does with a secret can be done over HTTPS with JSON. The common pattern is a script or pipeline that creates a secret and hands the link to a person, so the credential never sits in a log, a ticket or a chat history.

The full endpoint reference, with request and response schemas and a try-it console, lives at api.onetimesecret.com. This page covers what you need before you open it.

Requests go to the region that holds your account. Each region is a separate deployment and nothing is replicated between them.

https://REGION.onetimesecret.com/api/v2
REGIONHost
caca.onetimesecret.com
eueu.onetimesecret.com
nznz.onetimesecret.com
ukuk.onetimesecret.com
usus.onetimesecret.com

The bare onetimesecret.com host still answers API requests and routes to an active region, but pin a region explicitly so your integration keeps working if that fallback is retired. See Where your data lives for what each region means for your data.

On a custom domain, the API is at the same path on your domain, and links it creates use that domain:

https://secrets.example.com/api/v2

A self-hosted instance exposes the same API on whatever host you run it on.

Use HTTP Basic authentication. The username is your account email; the password is the API token from your account settings.

Terminal window
curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/status

Creating and revealing secrets also works without authentication, with the limits of an anonymous user: shorter maximum lifetime, smaller secret size, and no receipts list. Authenticated requests get your plan's limits and show up in your receipts.

Create a secret that lives for one hour:

Terminal window
curl -u 'you@example.com:APITOKEN' \
-H 'Content-Type: application/json' \
-d '{"secret": {"secret": "the password is hunter2", "ttl": 3600}}' \
https://eu.onetimesecret.com/api/v2/secret/conceal

The examples put the token and the secret in the command so they are easy to read. In real use, keep both out of it: a command is saved in your shell history, and other users of the same machine can see it in the process list. With -u 'you@example.com' and no token, curl asks for the token. With -d @secret.json, it reads the request body from a file that only you can read.

The response contains two records. record.secret.identifier is the key you share, as https://eu.onetimesecret.com/secret/IDENTIFIER. record.receipt.identifier is yours: it shows whether the secret has been viewed and lets you burn it early. Never send the receipt key to the recipient.

Add "passphrase": "..." to the secret object to require a passphrase on viewing. The passphrase is an access check, not the encryption key: the service stores only a one-way hash of it and checks it before decrypting the value. A lost passphrase cannot be recovered, so the secret can then be neither revealed nor burned; it is deleted when it expires.

Reveal a secret, which consumes it. The body must contain "continue": true; without it, the call returns the secret's metadata and leaves the value unread. If the secret has a passphrase, add "passphrase": "..." beside it:

Terminal window
curl -X POST -H 'Content-Type: application/json' -d '{"continue": true}' \
https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/reveal

Burn a secret before anyone views it, using the receipt key. Burning also requires "continue": true. If the secret has a passphrase, add "passphrase": "..." beside it, as for revealing:

Terminal window
curl -u 'you@example.com:APITOKEN' -X POST -H 'Content-Type: application/json' \
-d '{"continue": true}' \
https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burn
  • v2 is the current public API: JSON in and out, receipts, status and burn endpoints. Build on this one.
  • v1 is the original form-encoded API (POST /api/v1/share). It still works, and most community libraries use it, but new integrations should use v2.

Both are documented at api.onetimesecret.com.