API reference

Keys

The keys that protect your organization's data, your own keys for encrypting and signing, and your personal keys.

GET/v1/orgs/:orgId/keys

Every key that protects the org's data, grouped by app on the page: Drive, secrets, connectors, integrations and the org's own keys (keys:read). With only keys:use, the org's own keys. Also the plan's limits and this month's operations.

Auth: A person's token or an API key, as Authorization: Bearer.
Allowed: keys:read; keys:use

Get an API key

Path parameters

orgId
Organization id (org_…).

Errors

403Missing scope keys:read

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/keys' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  keys: {
    uses30d: number
    lastUsedAt: null | number
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
  }[]
  limits: {
    keysMax: number
    keyOpsPerMonth: number
    secretsMax: number
    keyMonthlyPriceCents: number
    keyOpsPer10kPriceCents: number
  }
  operationsThisMonth: number
}

POST/v1/orgs/:orgId/keys

Makes one of the org's own keys (keys:write).

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

Get an API key

Path parameters

orgId
Organization id (org_…).

Request body

namestringrequired
1–100 characters. Trimmed.
algorithm"aes-256-gcm" | "ed25519" | "ecdsa-p256"
Default "aes-256-gcm".
descriptionstring
Up to 500 characters.
scopeobject
scope.kind"org" | "project" | "environment"required
scope.idstringrequired
1–200 characters.
rotateEveryDaysinteger
1–3650.

Errors

400An org key's scope is the org.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Example"
  }'

Send it from this page with your session or a key.

Response 201

{
  key: {
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
  }
}

GET/v1/orgs/:orgId/keys/:keyId

A key: versions still in use, created, rotated, last used, uses in the last 30 days, recent re-encryption jobs.

Auth: A person's token or an API key, as Authorization: Bearer.
Allowed: keys:read; keys:use

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Errors

403Missing scope keys:read
404Key not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  key: {
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
    versions: {
      version: number
      createdAt: number
      current: boolean
      uses30d: number
      adopted: boolean
    }[]
    uses30d: number
    lastUsedAt: null | number
    usage: {
      day: string
      uses: number
    }[]
    canReencrypt: boolean
    jobs: {
      error?: string
      createdAt: number
      kind: "reencrypt"
      app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
      createdBy: string
      keyId: string
      total?: number
      startedAt?: number
      state: "queued" | "done" | "failed" | "running"
      jobId: string
      failed: number
      seen: number
      moved: number
      finishedAt?: number
      current: number
      toVersion: number
    }[]
  }
}

GET/v1/orgs/:orgId/keys/:keyId/audit

Who or what used the key, how and when (the org's audit log for this key; keys:read).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:read
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Query parameters

cursorstring
Up to 4,096 characters.
actionstring
Matches ^[a-z_]{1,32}(\.[a-z_]{1,32})?$.
actorstring
1–512 characters.
limitinteger
Default 50. 1–100. Coerced from a string.

Errors

400Invalid cursor
404Key not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/audit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  events: {
    eventId: string
    orgId: string
    action: string
    actor: {
      type: "user" | "key" | "device" | "system"
      id: string
      label?: string
    }
    target: {
      type: string
      id: string
      label?: string
    }
    metadata?: {
      [key: string]: unknown
    }
    ip?: string
    userAgent?: string
    createdAt: number
  }[]
  cursor: null | string
  retentionDays?: number
}

POST/v1/orgs/:orgId/keys/:keyId/rotate

A new version for new data; older versions keep decrypting. reencrypt: also move existing data to it, in the background.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

reencryptboolean
Default false.

Errors

404Key not found
409This key seals Tesla's access tokens, and only the Vehicles functions can open it, so it can't be rotated from here yet.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/rotate' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "reencrypt": false
  }'

Send it from this page with your session or a key.

Response 200

{
  job?: {
    error?: string
    createdAt: number
    kind: "reencrypt"
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    createdBy: string
    keyId: string
    total?: number
    startedAt?: number
    state: "queued" | "done" | "failed" | "running"
    jobId: string
    failed: number
    seen: number
    moved: number
    finishedAt?: number
    current: number
    toVersion: number
  }
  key: {
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
  }
}

POST/v1/orgs/:orgId/keys/:keyId/reencrypt

Moves existing data to the current version, in the background (where the app supports it).

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Errors

404Key not found
409This key seals Tesla's access tokens, and only the Vehicles functions can open it, so it can't be rotated from here yet.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/reencrypt' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 202

{
  job: {
    error?: string
    createdAt: number
    kind: "reencrypt"
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    createdBy: string
    keyId: string
    total?: number
    startedAt?: number
    state: "queued" | "done" | "failed" | "running"
    jobId: string
    failed: number
    seen: number
    moved: number
    finishedAt?: number
    current: number
    toVersion: number
  }
}

GET/v1/orgs/:orgId/keys/:keyId/jobs/:jobId

A re-encryption job's progress: state, seen, moved, current (already on the newest version), failed and total where known. Needs keys:read.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:read
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).
jobId
Job id: an agent job (job_…), under pipelines a pipeline job (pjb_…), or under crm an import or export (cjb_…); under marketing a list import (mkj_…).

Errors

404Key not found
404Job not found

curl 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/jobs/{jobId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  job: {
    error?: string
    createdAt: number
    kind: "reencrypt"
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    createdBy: string
    keyId: string
    total?: number
    startedAt?: number
    state: "queued" | "done" | "failed" | "running"
    jobId: string
    failed: number
    seen: number
    moved: number
    finishedAt?: number
    current: number
    toVersion: number
  }
}

PUT/v1/orgs/:orgId/keys/:keyId/schedule

Rotates every rotateEveryDays days from now; null turns the schedule off.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

rotateEveryDaysintegerrequiredor null
1–3650.

Errors

404Key not found
409This key seals Tesla's access tokens, and only the Vehicles functions can open it, so it can't be rotated from here yet.

curl -X PUT 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/schedule' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "rotateEveryDays": 1
  }'

Send it from this page with your session or a key.

Response 200

{
  key: {
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
  }
}

POST/v1/orgs/:orgId/keys/:keyId/disable

The org's own keys only: nothing seals or opens with a disabled key until it's enabled again.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Errors

400Only your organization's own keys can be turned off.
404Key not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/disable' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

POST/v1/orgs/:orgId/keys/:keyId/enable

Turns one of the organization's own keys back on after disable. Needs keys:write.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Errors

400Only your organization's own keys can be turned off.
404Key not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/enable' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

DELETE/v1/orgs/:orgId/keys/:keyId

Destroys one of the org's own keys, which must be disabled first: nothing it encrypted can be decrypted again.

Auth: A person's token or an API key, as Authorization: Bearer.
Scope: keys:write
Allowed: keys:read

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Errors

400Keys that protect the platform's data are destroyed with that data.
404Key not found
409Disable the key first.

curl -X DELETE 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 204 with no body

POST/v1/orgs/:orgId/keys/:keyId/encrypt

Encrypts up to 64 KB with an aes-256-gcm key. context: values the ciphertext is bound to; decrypting needs the same.

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

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

plaintextstringrequired
encoding"utf8" | "base64"
Default "utf8".
contextobject
Keys 1–128 characters. Values: string (up to 1,024 characters).

Errors

400Not base64.
404Key not found
413Up to 64 KB at a time.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/encrypt' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "plaintext": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  ciphertext: string
  keyId: string
  version: number
}

POST/v1/orgs/:orgId/keys/:keyId/decrypt

Decrypts a ciphertext (k1.…) made with this key, with the context it was encrypted with, as text (encoding: "utf8", the default) or base64. Any version of the key opens what it sealed. Counts towards the plan's monthly operations and is an audit event. Needs keys:use.

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

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

ciphertextstringrequired
1–200,000 characters.
encoding"utf8" | "base64"
Default "utf8".
contextobject
Keys 1–128 characters. Values: string (up to 1,024 characters).

Errors

404Key not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/decrypt' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ciphertext": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  plaintext: string
  keyId: string
  version: number
}

POST/v1/orgs/:orgId/keys/:keyId/rewrap

The same ciphertext under the key's current version, without the plaintext leaving the service.

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

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

ciphertextstringrequired
1–200,000 characters.
contextobject
Keys 1–128 characters. Values: string (up to 1,024 characters).

Errors

400This ciphertext was made with another key.
404Key not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/rewrap' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "ciphertext": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  ciphertext: string
  keyId: string
  version: number
}

POST/v1/orgs/:orgId/keys/:keyId/sign

Signs up to 64 KB with an ed25519 or ecdsa-p256 key (ECDSA signs the message's SHA-256).

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

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

messagestringrequired
encoding"utf8" | "base64"
Default "utf8".

Errors

400Not base64.
404Key not found
413Up to 64 KB at a time.

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/sign' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  signature: string
  keyId: string
  version: number
}

POST/v1/orgs/:orgId/keys/:keyId/verify

Checks a signature (k1s.…) from sign against message: { valid }. Counts towards the plan's monthly operations. Needs keys:use.

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

Get an API key

Path parameters

orgId
Organization id (org_…).
keyId
Key id (key_…).

Request body

messagestringrequired
signaturestringrequired
1–2,000 characters.
encoding"utf8" | "base64"
Default "utf8".

Errors

400Not base64.
404Key not found

curl -X POST 'https://api.cactive.com.au/v1/orgs/{orgId}/keys/{keyId}/verify' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "example",
    "signature": "example"
  }'

Send it from this page with your session or a key.

Response 200

{
  valid: boolean
  keyId: string
  version: number
}

GET/v1/me/keys

Your personal keys (Health, your own Drive and Photos space) with uses in the last 30 days and when last used. Never key material. Only you see them: people only, not API keys or connected apps.

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

Get an API key

Errors

403Only you can see your personal keys.

curl 'https://api.cactive.com.au/v1/me/keys' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  keys: {
    uses30d: number
    lastUsedAt: null | number
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
  }[]
}

GET/v1/me/keys/:keyId

One of your personal keys: versions still in use, created, last rotated, last used, uses in the last 30 days.

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

Get an API key

Path parameters

keyId
Key id (key_…).

Errors

403Only you can see your personal keys.
404Key not found

curl 'https://api.cactive.com.au/v1/me/keys/{keyId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  key: {
    keyId: string
    name: string
    description: null | string
    app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
    appLabel: string
    protects: string
    scope: {
      kind: "org" | "project" | "person" | "environment" | "space" | "vehicle"
      id: string
    }
    owner: "org" | "person"
    algorithm: "aes-256-gcm" | "ed25519" | "ecdsa-p256" | "s3"
    state: "disabled" | "enabled" | "destroyed"
    currentVersion: number
    managed: boolean
    createdAt: number
    rotatedAt: null | number
    rotateEveryDays: null | number
    nextRotationAt: null | number
    destroyedAt: null | number
    canRotate: boolean
    versions: {
      version: number
      createdAt: number
      current: boolean
      uses30d: number
      adopted: boolean
    }[]
    uses30d: number
    lastUsedAt: null | number
    usage: {
      day: string
      uses: number
    }[]
    canReencrypt: boolean
    jobs: {
      error?: string
      createdAt: number
      kind: "reencrypt"
      app: "keys" | "drive" | "health" | "vehicles" | "secrets" | "connectors" | "integrations" | "vehicles-tesla"
      createdBy: string
      keyId: string
      total?: number
      startedAt?: number
      state: "queued" | "done" | "failed" | "running"
      jobId: string
      failed: number
      seen: number
      moved: number
      finishedAt?: number
      current: number
      toVersion: number
    }[]
  }
}

GET/v1/me/keys/:keyId/audit

Your key's uses, from your own audit log (nobody else's log has them).

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

Get an API key

Path parameters

keyId
Key id (key_…).

Query parameters

cursorstring
Up to 4,096 characters.
actionstring
Matches ^[a-z_]{1,32}(\.[a-z_]{1,32})?$.
actorstring
1–512 characters.
limitinteger
Default 50. 1–100. Coerced from a string.

Errors

400Invalid cursor
403Only you can see your personal keys.
404Key not found

curl 'https://api.cactive.com.au/v1/me/keys/{keyId}/audit' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"

Send it from this page with your session or a key.

Response 200

{
  events: {
    eventId: string
    orgId: string
    action: string
    actor: {
      type: "user" | "key" | "device" | "system"
      id: string
      label?: string
    }
    target: {
      type: string
      id: string
      label?: string
    }
    metadata?: {
      [key: string]: unknown
    }
    ip?: string
    userAgent?: string
    createdAt: number
  }[]
  cursor: null | string
  retentionDays?: number
}