Retrieving Secrets
Updated 2025-04-02
Retrieve a Secret
Section titled “Retrieve a Secret”POST https://REGION.onetimesecret.com/api/v1/secret/SECRET_KEY
Authenticated Request
Section titled “Authenticated Request”$ curl -X POST -u 'USERNAME:APITOKEN' https://eu.onetimesecret.com/api/v1/secret/SECRET_KEYAnonymous Request
Section titled “Anonymous Request”$ curl -X POST https://eu.onetimesecret.com/api/v1/secret/SECRET_KEYQuery Params
Section titled “Query Params”- SECRET_KEY: the unique key for this secret.
- passphrase (if required): the passphrase is required only if the secret was created with one.
Attributes
Section titled “Attributes”- secret_key: the unique key for the secret you create. This is key that you can share.
- value: The actual secret. It should go without saying, but this will only be available one time.
Retrieve Metadata
Section titled “Retrieve Metadata”POST https://REGION.onetimesecret.com/api/v1/private/METADATA_KEY
Every secret also has associated metadata. The metadata is intended to be used by the creator of the secret (i.e. not the recipient) and should generally be kept private. You can safely use the metadata key to retrieve basic information about the secret itself (e.g. if or when it was viewed) since the metadata key is different from the secret key.
Authenticated Request
Section titled “Authenticated Request”$ curl -X POST -u 'USERNAME:APITOKEN' https://eu.onetimesecret.com/api/v1/private/METADATA_KEYQuery Params
Section titled “Query Params”- METADATA_KEY: the unique key for this metadata.
Attributes
Section titled “Attributes”- custid: the username of the account that created the secret. This value will be
anonfor anonymous requests. - metadata_key: the unique key for the metadata. DO NOT share this.
- secret_key: the unique key for the secret you created. This is key that you can share.
- ttl: The time-to-live that was specified (i.e. not the time remaining)
- metadata_ttl: The remaining time (in seconds) that the metadata has left to live.
- secret_ttl: The remaining time (in seconds) that the secret has left to live.
- recipient: if a recipient was specified, this is an obfuscated version of the email address.
- created: Time the metadata was created in unix time (UTC)
- updated: ditto, but the time it was last updated.
- received: Time the secret was received.
- passphrase_required: If a passphrase was provided when the secret was created, this will be true. Otherwise false, obviously.
Burn a Secret
Section titled “Burn a Secret”POST https://REGION.onetimesecret.com/api/v1/private/METADATA_KEY/burn
Burn a secret that has not been read yet.
Authenticated Request
Section titled “Authenticated Request”$ curl -X POST -u 'USERNAME:APITOKEN' https://eu.onetimesecret.com/api/v1/private/METADATA_KEY/burnQuery Params
Section titled “Query Params”- None
Attributes
Section titled “Attributes”- Same as metadata attributes with a status of burned.
Retrieve Recent Metadata
Section titled “Retrieve Recent Metadata”GET https://onetimesecret.com/api/v1/private/recent
Retrieve a list of recent metadata.
Authenticated Request
Section titled “Authenticated Request”$ curl -u 'USERNAME:APITOKEN' https://eu.onetimesecret.com/api/v1/private/recentQuery Params
Section titled “Query Params”- None
Attributes
Section titled “Attributes”- Same as metadata attributes, although as a list and the secret key value will always be null.
::: warning Authentication Required Note: Metadata and management operations (retrieve metadata, burn secret, recent metadata) are only available for authenticated users. :::