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.
Base URL
Section titled “Base URL”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/v2REGION | Host |
|---|---|
ca | ca.onetimesecret.com |
eu | eu.onetimesecret.com |
nz | nz.onetimesecret.com |
uk | uk.onetimesecret.com |
us | us.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/v2A self-hosted instance exposes the same API on whatever host you run it on.
Authentication
Section titled “Authentication”Use HTTP Basic authentication. The username is your account email; the password is the API token from your account settings.
curl -u 'you@example.com:APITOKEN' https://eu.onetimesecret.com/api/v2/statusCreating 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.
Quick start
Section titled “Quick start”Create a secret that lives for one hour:
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/concealThe 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:
curl -X POST -H 'Content-Type: application/json' -d '{}' \ https://eu.onetimesecret.com/api/v2/secret/IDENTIFIER/revealBurn a secret before anyone views it, using the receipt key:
curl -u 'you@example.com:APITOKEN' -X POST \ https://eu.onetimesecret.com/api/v2/receipt/RECEIPT_IDENTIFIER/burnAPI versions
Section titled “API versions”- 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.
Client libraries
Section titled “Client libraries”Related
Section titled “Related”- Where your data lives: choosing a region, and what stays inside it.
- Custom domains: secret links and API access on your own domain.
- Self-hosting: run the API on your own infrastructure.
- Developer on-ramp: run the application locally and contribute.