Docs
Developer Portal

API reference

Passwords vault

The Authenticator app's encrypted vault: the account and its sealed keys, vaults, items, devices and resets. The server stores ciphertext; every change is signed by the vault's own key.
Read the Guide
GET/v1/me/vault

Your Passwords vault as stored: account (the keyset sealed under your master password and Secret Key, the Argon2id settings and salt, the public keys) or null, vaults with their wrapped keys and counters, devices, a pending reset and limits. Everything that says what's in the vault is encrypted on your devices. From the Authenticator app's sign-in only.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Passwords opens only in the Authenticator app.
curl 'https://api.cactive.com.au/v1/me/vault' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  account: null | {
    createdAt: number
    updatedAt: number
    accountId: string
    kdfSalt: string
    keyset: string
    keysetRevision: number
    encryptionPublicKey: string
    signingPublicKey: string
    kdf: {
      alg: "argon2id"
      m: number
      t: number
      p: number
    }
  }
  vaults: {
    vaultId: string
    kind: "personal"
    role: "owner"
    envelope: string
    attrs: string
    attrsRevision: number
    revision: number
    itemCount: number
    createdAt: number
    updatedAt: number
  }[]
  devices: {
    deviceId: string
    name: string
    platform: string
    createdAt: number
    lastSeenAt: number
  }[]
  reset: null | {
    requestedAt: number
    at: number
  }
  limits: {
    maxItems: number
    maxDevices: 20
  }
}
POST/v1/me/vault

Makes your vault: the account, a personal vault and the first device, all sealed on the device and signed with the new vault's own key (X-Vault-Signature). 409 (exists) when you have one, unless its reset is due, when the old vault is deleted first.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body (up to 16 KB)

  • accountIdstringrequired
  • kdfobjectrequired
  • kdf.alg"argon2id"required
  • kdf.mintegerrequired
  • kdf.tintegerrequired
  • kdf.pintegerrequired
  • kdfSaltstringrequired

    Matches ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$.

  • keysetany JSONrequired
  • encryptionPublicKeystringrequired

    Matches ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$.

  • signingPublicKeystringrequired

    Matches ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$.

  • vaultobjectrequired
  • vault.vaultIdstringrequired

    Matches ^[A-Za-z0-9_-]{22}$.

  • vault.envelopeany JSONrequired
  • vault.attrsany JSONrequired
  • deviceobjectrequired
  • device.deviceIdstringrequired

    Matches ^[A-Za-z0-9_-]{22}$.

  • device.namestringrequired

    1–80 characters. Trimmed.

  • device.platform"ios" | "android" | "web"required

Also checked: Unknown fields are rejected.

Errors

  • 403Passwords opens only in the Authenticator app.
  • 409You already have a vault.
  • 413The request is too large.
curl -X POST 'https://api.cactive.com.au/v1/me/vault' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "accountId": "<accountId>",
    "kdf": {
      "alg": "argon2id",
      "m": 1,
      "t": 1,
      "p": 1
    },
    "kdfSalt": "example",
    "keyset": {},
    "encryptionPublicKey": "example",
    "signingPublicKey": "example",
    "vault": {
      "vaultId": "<vaultId>",
      "envelope": {},
      "attrs": {}
    },
    "device": {
      "deviceId": "<deviceId>",
      "name": "Example",
      "platform": "ios"
    }
  }'
Send it from this page with your session or a key.

Response 201

{
  account: null | {
    createdAt: number
    updatedAt: number
    accountId: string
    kdfSalt: string
    keyset: string
    keysetRevision: number
    encryptionPublicKey: string
    signingPublicKey: string
    kdf: {
      alg: "argon2id"
      m: number
      t: number
      p: number
    }
  }
  vaults: {
    vaultId: string
    kind: "personal"
    role: "owner"
    envelope: string
    attrs: string
    attrsRevision: number
    revision: number
    itemCount: number
    createdAt: number
    updatedAt: number
  }[]
  devices: {
    deviceId: string
    name: string
    platform: string
    createdAt: number
    lastSeenAt: number
  }[]
  reset: null | {
    requestedAt: number
    at: number
  }
  limits: {
    maxItems: number
    maxDevices: 20
  }
}
PUT/v1/me/vault/keyset

Replaces the sealed keyset after a new master password or Secret Key, if keysetRevision is still current (409 otherwise). Signed by the vault. Emails you.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Request body (up to 8 KB)

  • kdfobjectrequired
  • kdf.alg"argon2id"required
  • kdf.mintegerrequired
  • kdf.tintegerrequired
  • kdf.pintegerrequired
  • kdfSaltstringrequired

    Matches ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$.

  • keysetany JSONrequired
  • keysetRevisionintegerrequired

    ≥ 1.

Also checked: Unknown fields are rejected.

Errors

  • 403Passwords opens only in the Authenticator app.
  • 409The vault changed on another device.
  • 413The request is too large.
curl -X PUT 'https://api.cactive.com.au/v1/me/vault/keyset' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "kdf": {
      "alg": "argon2id",
      "m": 1,
      "t": 1,
      "p": 1
    },
    "kdfSalt": "example",
    "keyset": {},
    "keysetRevision": 1
  }'
Send it from this page with your session or a key.

Response 200

{
  account: {
    createdAt: number
    updatedAt: number
    accountId: string
    kdfSalt: string
    keyset: string
    keysetRevision: number
    encryptionPublicKey: string
    signingPublicKey: string
    kdf: {
      alg: "argon2id"
      m: number
      t: number
      p: number
    }
  }
}
DELETE/v1/me/vault

Signed by the vault: deletes it now (items, vaults, devices and keys; the log stays). Without a signature (you can't open it any more): asks for a reset (202, reset), which may happen 7 days later unless a device that can open the vault cancels it. Emails you either way.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Passwords opens only in the Authenticator app.
  • 404There's no vault for this account.
curl -X DELETE 'https://api.cactive.com.au/v1/me/vault' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  deleted: true
}

Response 202

{
  reset: {
    requestedAt: number
    at: number
  }
}
POST/v1/me/vault/reset/cancel

Cancels a pending reset. Signed by the vault.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Passwords opens only in the Authenticator app.
curl -X POST 'https://api.cactive.com.au/v1/me/vault/reset/cancel' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  reset: null
}
GET/v1/me/vault/vaults/:vaultId/index

The vault's counter (revision) and every item's itemId, revision and whether it was deleted, without ciphertext: devices compare it with their copy.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vaultId

    A Passwords vault's id: 22 base64url characters, made on the device.

Errors

  • 403Passwords opens only in the Authenticator app.
  • 404That vault isn't yours.
curl 'https://api.cactive.com.au/v1/me/vault/vaults/{vaultId}/index' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  revision: number
  items: {
    itemId: string
    revision: number
    deleted: boolean
  }[]
}
GET/v1/me/vault/vaults/:vaultId/items

Up to 100 items by id (ids, comma-separated): each item's sealed key, overview and details (absent for deleted ones), revision and times.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vaultId

    A Passwords vault's id: 22 base64url characters, made on the device.

Query parameters

  • idsstring

    Default "".

Errors

  • 400Ask for up to 100 item ids.
  • 403Passwords opens only in the Authenticator app.
  • 404That vault isn't yours.
curl 'https://api.cactive.com.au/v1/me/vault/vaults/{vaultId}/items' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  items: {
    itemId: string
    revision: number
    deleted: boolean
    key?: string
    overview?: string
    details?: string
    createdAt: number
    updatedAt: number
  }[]
}
POST/v1/me/vault/vaults/:vaultId/items

Writes up to 50 changes (a sealed key, overview and details, or deleted: true), each only if the item is still at its baseRevision (0: new; deletes go first). Per change: ok with the new revision, conflict with the item as it is now, or rejected (limit: the plan's item limit). Signed by the vault.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • vaultId

    A Passwords vault's id: 22 base64url characters, made on the device.

Request body (up to 4,096 KB)

  • changesobject[]required

    1–50 items.

  • changes[].itemIdstringrequired

    Matches ^[A-Za-z0-9_-]{22}$.

  • changes[].baseRevisionintegerrequired

    ≥ 0.

  • changes[].deletedtrue
  • changes[].keyany JSON
  • changes[].overviewany JSON
  • changes[].detailsany JSON

Also checked: Unknown fields are rejected. Each item can change once per request.

Errors

  • 403Passwords opens only in the Authenticator app.
  • 404That vault isn't yours.
  • 413Send fewer changes at once.
curl -X POST 'https://api.cactive.com.au/v1/me/vault/vaults/{vaultId}/items' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "changes": [
      {
        "itemId": "<itemId>",
        "baseRevision": 1
      }
    ]
  }'
Send it from this page with your session or a key.

Response 200

{
  results: {
    itemId: string
    status: "ok"
    revision: number
    deleted: boolean
    createdAt: number
    updatedAt: number
  } | {
    itemId: string
    status: "conflict"
    current: null | {
      itemId: string
      revision: number
      deleted: boolean
      key?: string
      overview?: string
      details?: string
      createdAt: number
      updatedAt: number
    }
  } | {
    itemId: string
    status: "rejected"
    code: "limit" | "invalid"
    error: string
  }[]
  vault: {
    revision: number
    itemCount: number
  }
}
PUT/v1/me/vault/devices/:deviceId

Registers this device (name, platform: ios, android or web) or renames it; signed by the vault with the device's own id. Up to 20 devices; a removed id can't come back. Emails you about a new device.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • deviceId

    Device id: an agent's (dev_…); under /v1/me/notifications a phone's install id; under /v1/me/sign-in-approvals a phone that approves sign-ins (apd_…); under /v1/me/vault the id a device made for its vault (22 base64url characters).

Request body (up to 4 KB)

  • namestringrequired

    1–80 characters. Trimmed.

  • platform"ios" | "android" | "web"required

Also checked: Unknown fields are rejected.

Errors

  • 403Passwords opens only in the Authenticator app.
  • 403This device was removed from your vault.
  • 409Your vault is on 20 devices already. Remove one first.
  • 413The request is too large.
curl -X PUT 'https://api.cactive.com.au/v1/me/vault/devices/{deviceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example",
    "platform": "ios"
  }'
Send it from this page with your session or a key.

Response 200

{
  device: {
    deviceId: string
    name: string
    platform: string
    createdAt: number
    lastSeenAt: number
  }
}
DELETE/v1/me/vault/devices/:deviceId

Removes a device; it stops syncing and wipes its copy when it next connects. Signed by the vault.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Path parameters

  • deviceId

    Device id: an agent's (dev_…); under /v1/me/notifications a phone's install id; under /v1/me/sign-in-approvals a phone that approves sign-ins (apd_…); under /v1/me/vault the id a device made for its vault (22 base64url characters).

Errors

  • 400Not a device id.
  • 403Passwords opens only in the Authenticator app.
curl -X DELETE 'https://api.cactive.com.au/v1/me/vault/devices/{deviceId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  removed: boolean
}
GET/v1/me/vault/activity

Your vault's log, newest first, kept a year: made, devices added and removed, master password or Secret Key changes, resets, deletion, and counts of changed items. Never contents.

Auth
A person's token or an API key, as Authorization: Bearer.
Get an API key

Errors

  • 403Passwords opens only in the Authenticator app.
curl 'https://api.cactive.com.au/v1/me/vault/activity' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  events: {
    at: number
    counts?: {
      [key: string]: number
    }
    deviceName?: string
    deviceId?: string
    activityId: string
    action: string
  }[]
}