Documentation

Create a secret and decide who gets it

A secret holds a value and the rules for handing it out. Pick an integration, write the rules, and Aker takes care of the rest.

Create it in the app

Open a stash and choose Add secret. Give it a name, pick an integration, and fill in the form. Add a rule for each group of people who should get a value. The form checks input against the same rules a read uses, so a secret that saves will run.

The same secret over the API:

{
  "name": "prod-database",
  "expiresAt": "2026-12-31T00:00:00.000Z",
  "rules": [
    {
      "id": "contractors",
      "name": "Contractors: read-only, 15 minutes",
      "match": { "roles": ["contractor"] },
      "action": {
        "actionset": "pgsql",
        "action": "create-role",
        "params": {
          "connectionString": "postgresql://aker_root:…@db.internal:5432/app",
          "rolePrefix": "aker",
          "attributes": ["LOGIN"],
          "ttlMinutes": 15,
          "tables": [
            { "schema": "public", "table": "orders", "permissions": ["SELECT"] }
          ],
          "allowRequest": { "ttlMinutes": true }
        }
      }
    },
    {
      "id": "engineering",
      "name": "Engineering: read-write",
      "match": { "teams": ["platform"] },
      "rules": [
        {
          "id": "canary",
          "match": { "context": { "deploy": "canary" } },
          "action": { "actionset": "generator", "action": "faker",
            "params": { "module": "internet", "method": "username" } }
        }
      ],
      "action": {
        "actionset": "pgsql",
        "action": "create-role",
        "params": {
          "connectionString": "postgresql://aker_root:…@db.internal:5432/app",
          "tables": [{ "schema": "public", "table": "*", "permissions": ["SELECT","INSERT","UPDATE"] }]
        }
      }
    }
  ]
}

What a match can test

Every key you add has to match. Within a key, one of the listed values is enough. A misspelled key is rejected rather than ignored, so a typo cannot widen the rule.

Key	Matches
`users`	Named people in the organisation (user ids or emails).
`emails`	Email patterns, case-insensitive, with `*` as a wildcard.
`userType`	`human`, `bot`, or both.
`teams`	Any of these team names.
`roles`	Any of these role names.
`channel`	The client channel the caller reports (`ui`, `mcp`, …).
`context`	Context variables the caller sends, matched as patterns.

Editing and expiry

PATCH /api/stashes/:stashId/secrets/:secretId replaces the whole rule list. The list is write-only: reading a secret back shows the ids, names, matches and integration keys, never the parameters. Replacing the list also drops any state the old rules created.

An edit is not a rotation, so the version number stays put. Set expiresAt when a secret should stop working on its own. Reads fail as soon as it expires, and Aker then revokes the issued value and deletes the secret. It checks every minute by default.