Documentation

Set up a secret, then use it

Store a value once. Decide who gets it. Read it from your code when you need it, in the form that fits the job: a password, a short-lived database login, a fresh token.

Quickstart

Everything you need is at one address. Sign in, create a stash, add a secret, then read it back with a credential from Authentication. 

# a credential, sent as a header (see Authentication)
export AKER_AUTH='<credential header>'

# who you are, and which organisations you belong to
curl -s https://app.aker.tech/api/me -H "$AKER_AUTH"

# a stash to hold secrets
curl -s https://app.aker.tech/api/stashes -H "$AKER_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"organizationId":"<orgId>","name":"platform","readRoles":["admin","developer"]}'

# a secret that returns one stored value
curl -s https://app.aker.tech/api/stashes/<stashId>/secrets -H "$AKER_AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"name":"stripe-key","rules":[{"id":"everyone","match":{},
       "action":{"actionset":"raw","action":"serve","params":{"value":"sk_live_…"}}}]}'

# read it (by id, so the name stays out of the URL)
curl -s https://app.aker.tech/api/stashes/<stashId>/secrets/<secretId> -H "$AKER_AUTH"

A read returns the metadata plus value. A list never returns values.

How it fits together

  • Stash. A named container inside an organisation. Roles decide who can read values and who can edit settings. The person who creates it owns it.
  • Secret. A name, optional notes, an optional expiry date, and a set of access rules. Stored encrypted, with its own key. Addressed by id, so names never appear in URLs or request logs.
  • Access rules. An ordered list, checked from the top. The first rule that matches the caller wins. A rule with an empty match applies to everyone. If nothing matches, the request is refused and reads as not found.
  • Action. What the matching rule does: return a stored value, mint a database login, read a cache key, generate a token.
  • Issued value. Each value handed out is recorded, so you can see who received what and revoke one value without touching the secret. Where the integration supports it, revoking also removes the credential upstream.
  • What the caller controls. Who the caller is, and their teams and roles, comes from the credential. The channel, request parameters, and context variables are supplied by the caller, so use them to shape a response or to label an audit trail, not as the only check on a real value.

Limits

Item Value
Session keys Expire after 7 days, and a credential never appears in a URL or a response body.
Integration timeout 10 seconds. A failed read is treated as a miss; a failed revoke is logged and skipped.
Expiry sweep Checked every 60 seconds. An expiring secret is revoked, then deleted.
Value size 64 KiB per read. Anything larger is treated as a miss.
Issued values One record per read. A rotation marks earlier records as superseded; a plain read does not.
Name lookup Names are indexed per stash and never stored in plain text, and never appear in a URL.
Audit Every read and every change is recorded. Records hold random ids, never names or values.

Rules are write-only and parameters are never returned by a read, so keep your own copy in your repository if you want changes reviewed before they ship.

Next Authentication