Creating & Reading Secrets

BETA API - updated 2017-04-27 (Have a question?)

Create a Secret

POST https://transfer.aweos.de/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.
  • recipient: an email address. We will send a friendly email containing the secret link (NOT the secret itself).
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.
  • recipient: if a recipient was specified, this is an obfuscated version of the email address.
  • 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]' https://transfer.aweos.de/api/v1/share
{
  "custid":"USERNAME",
  "metadata_key":"qjpjroeit8wra0ojeyhcw5pjsgwtuq7",
  "secret_key":"153l8vbwqx5taskp92pf05uvgjefvu9",
  "ttl":"3600",
  "updated":"1324174006",
  "created":"1324174006"
}

Generate a Secret

POST https://transfer.aweos.de/api/v1/generate

Generate a short, unique secret. This is useful for temporary passwords, one-time pads, salts, etc.

Query Params
  • 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.
  • recipient: an email address. We will send a friendly email containing the secret link (NOT the secret itself).
$ curl -d 'secret=SECRET&ttl=NUMBER_IN_SECONDS'  -u 'USERNAME:APITOKEN' https://transfer.aweos.de/api/v1/generate
{
  "custid":"USERNAME",
  "value":"3Rg8R2sfD3?a",
  "metadata_key":"2b6bjmudhmtiqjn2qmdaqjkqxp323gi",
  "secret_key":"pgcdv7org3vtdurif809sygnt0mstw6",
  "ttl":"3600",
  "updated":"1324174095",
  "created":"1324174095"
}

Attributes
Same as Share A Secret above, with the addition of the value field.

Retrieve a Secret

POST https://transfer.aweos.de/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' https://transfer.aweos.de/api/v1/secret/SECRET_KEY

Retrieve Metadata

POST https://transfer.aweos.de/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.

Query Params
  • METADATA_KEY: the unique key for this metadata.
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 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.
Example: 
$ curl -X POST -u 'USERNAME:APITOKEN' https://transfer.aweos.de/api/v1/private/METADATA_KEY

Burn a secret

POST https://transfer.aweos.de/api/v1/private/METADATA_KEY/burn

Burn a secret that has not been read yet.

Query Params
  • None
Attributes
  • Same as metadata attributes with a status of burned.
Example: 
$ curl -X POST -u 'USERNAME:APITOKEN' https://transfer.aweos.de/api/v1/private/METADATA_KEY/burn



Retrieve Recent Metadata

GET https://transfer.aweos.de/api/v1/private/recent

Retreive a list of recent metadata.

Query Params
  • None
Attributes
  • Same as metadata attributes, although as a list and the secret key value will always be null.
Example: 
$ curl -u 'USERNAME:APITOKEN' https://transfer.aweos.de/api/v1/private/recent