Vaults & secrets

All requests below use Authorization: Bearer <access_token> — see Authentication. List endpoints accept ?limit= and ?cursor= — see Response format & pagination.

Vault fields

{
  "id": "429110bc-...",
  "org_id": "7a1c2e3f-...",
  "name": "My API",
  "icon_index": 4,
  "color": "#4F46E5",
  "team_id": null,
  "role": "admin",
  "created_at": "2026-01-15T10:20:30.000Z"
}

role is the calling key or user's own role on this vault: admin, editor, or member.

GET /v1/vaults

Every vault visible to the caller, newest first.

curl -s https://api.oneguard.one/v1/vaults \
  -H "Authorization: Bearer $TOKEN"

POST /v1/vaults

curl -s https://api.oneguard.one/v1/vaults \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Marketing site"}'

Returns 201 with the created vault and a Location header.

GET /v1/vaults/{vaultId}

curl -s https://api.oneguard.one/v1/vaults/{vaultId} \
  -H "Authorization: Bearer $TOKEN"

PATCH /v1/vaults/{vaultId}

Partial update — any of name, team_id, icon_index, color. Fields left out keep their current value. Send "team_id": null to remove a vault from its team.

curl -s https://api.oneguard.one/v1/vaults/{vaultId} \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New name"}'

DELETE /v1/vaults/{vaultId}

204 No Content on success.

curl -s https://api.oneguard.one/v1/vaults/{vaultId} \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

Vault members

{
  "id": "9e2a...",
  "vault_id": "429110bc-...",
  "user": { "id": "3f1a...", "name": "Sam", "email": "sam@example.com" },
  "role": "editor",
  "created_at": "2026-02-01T09:00:00.000Z"
}

GET /v1/vaults/{vaultId}/members — paginated list.

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/members \
  -H "Authorization: Bearer $TOKEN"

POST /v1/vaults/{vaultId}/members adds one.

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/members \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"3f1a...","role":"editor"}'

PATCH /v1/vaults/{vaultId}/members/{memberId} changes a member's role, and returns just {"id", "vault_id", "role"} — not the full member object.

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/members/{memberId} \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

DELETE /v1/vaults/{vaultId}/members/{memberId} removes one — 204 No Content.

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/members/{memberId} \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

Secret fields

{
  "id": "3cb0cce2-...",
  "vault_id": "429110bc-...",
  "name": "production",
  "type": "env",
  "expired_at": null,
  "delete_after_expired": false,
  "is_archived": false,
  "created_at": "2026-02-01T09:00:00.000Z"
}

GET /v1/vaults/{vaultId}/secrets

Paginated metadata list — no values.

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/secrets \
  -H "Authorization: Bearer $TOKEN"

POST /v1/vaults/{vaultId}/secrets

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/secrets \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "value": {
      "DB_PASSWORD": "supersecret",
      "API_KEY": "sk_live_..."
    }
  }'

Returns 201 with the metadata shape above (never the value you just sent) and a Location header.

PATCH /v1/secrets/{secretId}

Partial: send name and/or value. A value you send replaces the entire stored value — it is not merged key by key.

curl -s https://api.oneguard.one/v1/secrets/{secretId} \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":{"DB_PASSWORD":"new-password"}}'

DELETE /v1/secrets/{secretId}

Archives the secret (soft delete — it stops appearing in listings). 204 No Content.

curl -s https://api.oneguard.one/v1/secrets/{secretId} \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

GET /v1/secrets/{secretId}/value

The metadata shape plus a decrypted value object. See the Quickstart for a full example.

curl -s https://api.oneguard.one/v1/secrets/{secretId}/value \
  -H "Authorization: Bearer $TOKEN"

GET /v1/vaults/{vaultId}/secrets/values

Every live secret of a vault, each with its decrypted value, in one uncursored call:

curl -s https://api.oneguard.one/v1/vaults/{vaultId}/secrets/values \
  -H "Authorization: Bearer $TOKEN"

{
  "statusCode": 200,
  "errorCode": null,
  "message": null,
  "data": [
    { "id": "...", "name": "production", "...": "...", "value": { "DB_PASSWORD": "..." } },
    { "id": "...", "name": "staging", "...": "...", "value": { "DB_PASSWORD": "..." } }
  ]
}

No next_cursor on this one — see the pagination note for why.