Docs
Developer Portal

API reference

Sign-in approvals

The Authenticator app's side of sign-in approvals: requests waiting for an answer, the signed answer, enrolling the phone's key, and signing out everywhere after No.
Read the Guide
GET/v1/me/sign-in-approvals/settings

Sign-in approvals for your account: on, pausedUntil (epoch ms, while requests are paused after denials), the phones that approve (devices: name, model, system, where the key lives, when added and last used; never keys) and twoStep (whether the account has a code to fall back to; requests need one). 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

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

Response 200

{
  twoStep: boolean
  on: boolean
  pausedUntil?: number
  devices: {
    deviceId: string
    name: string
    model?: string
    os?: string
    keyStorage: "secure-enclave" | "keychain" | "keystore"
    createdAt: number
    lastUsedAt?: number
  }[]
}
GET/v1/me/sign-in-approvals/requests

Sign-in requests waiting for an answer, newest first: what's signing in (app), from which browser (device), roughly where (place), createdAt and expiresAt. No numbers. What the app shows when it opens, for a notification that never arrived.

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

Errors

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

Response 200

{
  requests: {
    approvalId: string
    app: string
    device?: string
    place?: string
    createdAt: number
    expiresAt: number
  }[]
}
GET/v1/me/sign-in-approvals/requests/:approvalId

One waiting request with the three numbers to show (choices), the account (userId, email) and the binding the answer is signed with; 404 once answered, withdrawn or expired.

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

Path parameters

  • approvalId

    Approval id (apr_…): an issue's, from its approvals; under /v1/me/sign-in-approvals a sign-in request.

Errors

  • 403Sign-in approvals open only in the Authenticator app.
  • 404This request was answered or has expired.
curl 'https://api.cactive.com.au/v1/me/sign-in-approvals/requests/{approvalId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN"
Send it from this page with your session or a key.

Response 200

{
  request: {
    approvalId: string
    app: string
    device?: string
    place?: string
    createdAt: number
    expiresAt: number
    userId: string
    email: string
    choices: number[]
    binding: string
  }
}
POST/v1/me/sign-in-approvals/requests/:approvalId

Answers a request from this phone (deviceId): decision approve with the number tapped, or deny, with signature (see above). The right number approves; another number or deny denies (reason wrong_number or not_me, and paused when requests are now paused for an hour). 403 when the signature doesn't verify or the phone was removed, 409 when already answered or expired, 429 past 20 answers in 15 minutes.

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

Path parameters

  • approvalId

    Approval id (apr_…): an issue's, from its approvals; under /v1/me/sign-in-approvals a sign-in request.

Request body (up to 4 KB)

  • deviceIdstringrequired

    Up to 64 characters.

  • decision"approve" | "deny"required
  • numberinteger

    10–99.

  • signaturestringrequired

    8–200 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Sign-in approvals open only in the Authenticator app.
curl -X POST 'https://api.cactive.com.au/v1/me/sign-in-approvals/requests/{approvalId}' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "<deviceId>",
    "decision": "approve",
    "signature": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  status: string
  reason?: "not_me" | "wrong_number"
  paused?: boolean
}
POST/v1/me/sign-in-approvals/devices

Enrols this phone's key: publicKey, keyStorage (secure-enclave, keychain or keystore), name, optional model, os, appVersion, installId, timeZone, with signedAt and the key's signature over the enrolment message. 201 with the device (200 for a key already enrolled); the same phone's older key is replaced; up to 10 phones. 403 with code: "reauth" until the app's sign-in is recent and two-step or a passkey. Turns approvals on.

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

Request body (up to 4 KB)

  • publicKeystringrequired

    Up to 100 characters.

  • keyStorage"secure-enclave" | "keychain" | "keystore"required
  • namestringrequired

    Up to 200 characters.

  • modelstring

    Up to 200 characters.

  • osstring

    Up to 100 characters.

  • appVersionstring

    Up to 100 characters.

  • installIdstring

    Up to 128 characters.

  • timeZonestring

    Up to 64 characters.

  • signedAtintegerrequired
  • signaturestringrequired

    8–200 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Sign-in approvals open only in the Authenticator app.
curl -X POST 'https://api.cactive.com.au/v1/me/sign-in-approvals/devices' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "publicKey": "example",
    "keyStorage": "secure-enclave",
    "name": "Example",
    "signedAt": 1,
    "signature": "example"
  }'
Send it from this page with your session or a key.
DELETE/v1/me/sign-in-approvals/devices/:deviceId

Removes a phone: it gets no more requests and its answers are refused.

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

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

Response 204 with no body

POST/v1/me/sign-in-approvals/secure

Signs your account out everywhere but this app, after this phone answered a request with No (approvalId, within 30 minutes): every browser session at ID with the web apps' sign-ins from them, every other phone app and every command-line sign-in. Signed with the phone's key (deviceId, signedAt, signature). Returns how many browsers, apps and commandLine sign-ins ended.

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

Request body (up to 4 KB)

  • deviceIdstringrequired

    Up to 64 characters.

  • approvalIdstringrequired

    Up to 64 characters.

  • signedAtintegerrequired
  • signaturestringrequired

    8–200 characters.

Also checked: Unknown fields are rejected.

Errors

  • 403Sign-in approvals open only in the Authenticator app.
curl -X POST 'https://api.cactive.com.au/v1/me/sign-in-approvals/secure' \
  -H "Authorization: Bearer $CACTIVE_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "deviceId": "<deviceId>",
    "approvalId": "<approvalId>",
    "signedAt": 1,
    "signature": "example"
  }'
Send it from this page with your session or a key.

Response 200

{
  browsers: number
  apps: number
  commandLine: number
}