{{>header}}

<div id="content">
  <div id="documentation">
    <h2 class="intro">Creating &amp; Reading Secrets</h2>

    <ul id="docnav">
      <li class=""><a href="/docs/api" title="">Overview</a></li>
      <li class="selected"><a href="/docs/api/secrets" title="">Secrets</a></li>
      <li class=""><a href="/docs/api/libs" title="">Client Libraries</a></li>
    </ul>

    <p class="centre"><em class="larger">BETA API - updated 2017-04-27 (<a href="#feedback">Have a question?</a>)</em></p>

    <div id="topicContent">

      <h3 class="cufon docTitle dotted">Create a Secret</h3>
      <span class="docSubtext">POST {{baseuri}}/api/v1/share</span>

      <p>
        Use this method to store a secret value.
      </p>

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><span class="name">secret</span>: the secret value which is encrypted before being stored. There is a maximum length based on your plan that is enforced (1k-10k).</li>
          <li><span class="name">passphrase</span>: 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.</li>
          <li><span class="name">ttl</span>: 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.</li>
          <li><span class="name">recipient</span>: an email address. We will send a friendly email containing the secret link (NOT the secret itself).</li>
        </ul>
      </div>

      <div class="options">
        <strong>Attributes</strong>
        <ul>
          <li><span class="name">custid</span>: this is you :]</li>
          <li><span class="name">metadata_key</span>: the unique key for the metadata. DO NOT share this.</li>
          <li><span class="name">secret_key</span>: the unique key for the secret you create. This is key that you can share.</li>
          <li><span class="name">ttl</span>: The time-to-live (in seconds) that was specified (i.e. not the time remaining)</li>
          <li><span class="name">metadata_ttl</span>: The remaining time (in seconds) that the metadata has left to live.</li>
          <li><span class="name">secret_ttl</span>: The remaining time (in seconds) that the secret has left to live.</li>
          <li><span class="name">recipient</span>: if a recipient was specified, this is an obfuscated version of the email address.</li>
          <li><span class="name">created</span>: Time the secret was created in unix time (UTC)</li>
          <li><span class="name">updated</span>: ditto, but the time it was last updated.</li>
          <li><span class="name">passphrase_required</span>: If a passphrase was provided when the secret was created, this will be true. Otherwise false, obviously.</li>
        </ul>
      </div>

      <strong>Example:</strong>

      <pre class="colourize">$ curl -d 'secret=SECRET&amp;ttl=NUMBER_IN_SECONDS' -u 'USERNAME:APITOKEN' -F 'secret=[SECRET]' {{baseuri}}/api/v1/share</pre>
      <pre class="colourize">{
  "custid":"USERNAME",
  "metadata_key":"qjpjroeit8wra0ojeyhcw5pjsgwtuq7",
  "secret_key":"153l8vbwqx5taskp92pf05uvgjefvu9",
  "ttl":"3600",
  "updated":"1324174006",
  "created":"1324174006"
}</pre>

      <h3 class="cufon docTitle dotted">Generate a Secret</h3>
      <span class="docSubtext">POST {{baseuri}}/api/v1/generate</span>

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

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><span class="name">passphrase</span>: 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.</li>
          <li><span class="name">ttl</span>: 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.</li>
          <li><span class="name">recipient</span>: an email address. We will send a friendly email containing the secret link (NOT the secret itself).</li>
        </ul>
      </div>

      <pre class="colourize">$ curl -d 'secret=SECRET&amp;ttl=NUMBER_IN_SECONDS'  -u 'USERNAME:APITOKEN' {{baseuri}}/api/v1/generate</pre>

      <pre class="colourize">{
  "custid":"USERNAME",
  "value":"3Rg8R2sfD3?a",
  "metadata_key":"2b6bjmudhmtiqjn2qmdaqjkqxp323gi",
  "secret_key":"pgcdv7org3vtdurif809sygnt0mstw6",
  "ttl":"3600",
  "updated":"1324174095",
  "created":"1324174095"
}</pre>

      <p></p>

      <div class="options">
        <strong>Attributes</strong><br/>
        <em>Same as Share A Secret above, with the addition of the <tt>value</tt> field.</em>
      </div>


      <h3 class="cufon docTitle dotted">Retrieve a Secret</h3>
      <span class="docSubtext">POST {{baseuri}}/api/v1/secret/SECRET_KEY</span>

      <p>

      </p>

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><span class="name">SECRET_KEY</span>: the unique key for this secret.</li>
          <li><span class="name">passphrase</span> (if required): the passphrase is required only if the secret was create with one.</li>
        </ul>
      </div>

      <div class="options">
        <strong>Attributes</strong>
        <ul>
          <li><span class="name">secret_key</span>: the unique key for the secret you create. This is key that you can share.</li>
          <li><span class="name">value</span>: The actual secret. It should go without saying, but this will only be available one time.</li>
        </ul>
      </div>

      <strong>Example:</strong>

      <pre class="colourize">$ curl -X POST -u 'USERNAME:APITOKEN' {{baseuri}}/api/v1/secret/SECRET_KEY</pre>


      <h3 class="cufon docTitle dotted">Retrieve Metadata</h3>
      <span class="docSubtext">POST {{baseuri}}/api/v1/private/METADATA_KEY</span>

      <p>
        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.
      </p>

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><span class="name">METADATA_KEY</span>: the unique key for this metadata.</li>
<!--
          <li><span class="name">passphrase</span> (if required): the passphrase is required only if the secret was create with one.</li>
-->
        </ul>
      </div>

      <div class="options">
        <strong>Attributes</strong>
        <ul>
          <li><span class="name">custid</span>: this is you :]</li>
          <li><span class="name">metadata_key</span>: the unique key for the metadata. DO NOT share this.</li>
          <li><span class="name">secret_key</span>: the unique key for the secret you created. This is key that you can share.</li>
          <li><span class="name">ttl</span>: The time-to-live that was specified (i.e. not the time remaining)</li>
          <li><span class="name">metadata_ttl</span>: The remaining time (in seconds) that the metadata has left to live.</li>
          <li><span class="name">secret_ttl</span>: The remaining time (in seconds) that the secret has left to live.</li>
          <li><span class="name">recipient</span>: if a recipient was specified, this is an obfuscated version of the email address.</li>
          <li><span class="name">created</span>: Time the metadata was created in unix time (UTC)</li>
          <li><span class="name">updated</span>: ditto, but the time it was last updated.</li>
          <li><span class="name">received</span>: Time the secret was received.</li>
          <li><span class="name">passphrase_required</span>: If a passphrase was provided when the secret was created, this will be true. Otherwise false, obviously.</li>
        </ul>
      </div>

      <strong>Example:</strong>

      <pre class="colourize">$ curl -X POST -u 'USERNAME:APITOKEN' {{baseuri}}/api/v1/private/METADATA_KEY</pre>


      <h3 class="cufon docTitle dotted">Burn a secret</h3>
      <span class="docSubtext">POST {{baseuri}}/api/v1/private/METADATA_KEY/burn</span>

      <p>
        Burn a secret that has not been read yet.
      </p>

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><em>None</em></li>
        </ul>
      </div>

      <div class="options">
        <strong>Attributes</strong>
          <ul>
            <li><em>Same as metadata attributes with a status of burned.</em></li>
          </ul>
        <div>
      </div>

      <strong>Example:</strong>

      <pre class="colourize">$ curl -X POST -u 'USERNAME:APITOKEN' {{baseuri}}/api/v1/private/METADATA_KEY/burn</pre>

      <br/><br/><br/>
    </div>


      <h3 class="cufon docTitle dotted">Retrieve Recent Metadata</h3>
      <span class="docSubtext">GET {{baseuri}}/api/v1/private/recent</span>

      <p>
        Retreive a list of recent metadata.
      </p>

      <div class="options">
        <strong>Query Params</strong>
        <ul>
          <li><em>None</em></li>
        </ul>
      </div>

      <div class="options">
        <strong>Attributes</strong>
          <ul>
            <li><em>Same as metadata attributes, although as a list and the secret key value will always be null.</em></li>
          </ul>
        <div>
      </div>

      <strong>Example:</strong>

      <pre class="colourize">$ curl -u 'USERNAME:APITOKEN' {{baseuri}}/api/v1/private/recent</pre>

      <br/><br/><br/>
    </div>
  </div>
</div>

{{>footer}}