Base URI
http://onetimesecret.groundtruth.com/api
All API access is over HTTPS and starts with /api. All responses are JSON.
System Status
GET http://onetimesecret.groundtruth.com/api/v1/status
Current status of the system.
Parameters
None
Attributes
- status: The current system status. One of: nominal, offline.
Example:
$ curl -u 'USERNAME:APITOKEN' http://onetimesecret.groundtruth.com/api/v1/status
{"status":"nominal"}
Create a Secret
POST http://onetimesecret.groundtruth.com/api/v1/share
Use this method to store a secret value.
Query Params
- secret: the secret value which is encrypted before being stored. There is a maximum length based on your plan that is enforced (1k-10k).
- passphrase: a string that the recipient must know to view the secret. This value is also used to encrypt the secret and is bcrypted before being stored so we only have this value in transit.
- ttl: the maximum amount of time, in seconds, that the secret should survive (i.e. time-to-live). Once this time expires, the secret will be deleted and not recoverable.
Attributes
- custid: this is you :]
- metadata_key: the unique key for the metadata. DO NOT share this.
- secret_key: the unique key for the secret you create. This is key that you can share.
- ttl: The time-to-live (in seconds) 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.
- created: Time the secret was created in unix time (UTC)
- updated: ditto, but the time it was last updated.
- passphrase_required: If a passphrase was provided when the secret was created, this will be true. Otherwise false, obviously.
Example:
$ curl -d 'secret=SECRET&ttl=NUMBER_IN_SECONDS' -u 'USERNAME:APITOKEN' -F 'secret=[SECRET]' http://onetimesecret.groundtruth.com/api/v1/share
{
"custid":"USERNAME",
"metadata_key":"qjpjroeit8wra0ojeyhcw5pjsgwtuq7",
"secret_key":"153l8vbwqx5taskp92pf05uvgjefvu9",
"ttl":"3600",
"updated":"1324174006",
"created":"1324174006"
}
Retrieve a Secret
POST http://onetimesecret.groundtruth.com/api/v1/secret/SECRET_KEY
Query Params
- SECRET_KEY: the unique key for this secret.
- passphrase (if required): the passphrase is required only if the secret was create with one.
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.
Example:
$ curl -X POST -u 'USERNAME:APITOKEN' http://onetimesecret.groundtruth.com/api/v1/secret/SECRET_KEY
Burn a secret
POST http://onetimesecret.groundtruth.com/api/v1/private/METADATA_KEY/burn
Burn a secret that has not been read yet.
Attributes
- Same as metadata attributes with a status of burned.
Example:
$ curl -X POST -u 'USERNAME:APITOKEN' http://onetimesecret.groundtruth.com/api/v1/private/METADATA_KEY/burn