Skip to content

API reference

Okta accounts

What the next Okta run sends (new accounts, activations, changes, suspensions), the accounts linked to people, confirming and retrying, and the Okta groups to map teams and job families to. Confirming happens in the web app.

5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

Preview Okta provisioning#

POST/v1/org/okta.previewRead

What the next Okta run sends (nothing is sent): suspensions of leavers (the day after their last day; never deleted), new accounts (created staged from days_before the start; waiting_for_confirm: HR confirms them in Bizisy), activations on the first day (Okta emails its activation link to the work email), reactivations of rehires, and changes (fields: given_name, family_name, title, department, manager_id, groups), each with its last error. accounts: the people linked to Okta accounts or kept out (excluded), with Okta's status; administrators are never changed. connection: the Okta connection (integrations_connections_get okta for its health). Owners, admins and HR; never custom roles.

Who can call it
Manage key owner admin hr
MCP tool
org_okta_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • connectionobjectrequired
    5 fields
    • offeredbooleanrequired
    • status"none" | "connecting" | "connected" | "error" | "removed"required
    • labelstring | nullrequired
    • connected_atstring | nullrequired
    • last_run_atstring | nullrequired
  • countsobjectrequired
    6 fields
    • linkedintegerrequired
    • excludedintegerrequired
    • adminintegerrequired
    • pendingintegerrequired
    • waiting_for_confirmintegerrequired
    • failedintegerrequired
  • itemsobject[]required
    9 fields
    • kind"create" | "update" | "suspend" | "reactivate" | "activate"required
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • emailstringrequired
    • fieldsstring[]required

      update: the fields that differ (given_name, family_name, title, department, manager_id, groups).

    • waiting_for_confirmbooleanrequired
    • start_datestring | nullrequired
    • last_errorstring | nullrequired
    • failuresintegerrequired
    • held"new_link" | "many"required

      Why a change waits for a person: new_link (the first change since the account was linked: check it is theirs), many (many suspensions at once: an owner or admin confirms each).

  • accountsobject[]required
    9 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • emailstringrequired
    • statusstring | nullrequired

      Okta's status when Bizisy last looked: STAGED, PROVISIONED (activation sent), ACTIVE, SUSPENDED, DEPROVISIONED, …; null when no account was found.

    • linkedbooleanrequired
    • excludedbooleanrequired
    • adminbooleanrequired

      An Okta administrator: Bizisy never changes it.

    • created_by_bizisybooleanrequired
    • last_errorstring | nullrequired
    • failuresintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/okta.preview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "connection": {
      "offered": true,
      "status": "connected",
      "label": "acme.okta.com",
      "connected_at": "2026-10-01T09:00:00.000Z",
      "last_run_at": "2026-10-04T10:00:00.000Z"
    },
    "counts": {
      "linked": 24,
      "excluded": 1,
      "admin": 2,
      "pending": 1,
      "waiting_for_confirm": 1,
      "failed": 0
    },
    "items": [
      {
        "kind": "create",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "email": "ines@acme.test",
        "fields": [],
        "waiting_for_confirm": true,
        "start_date": "2026-10-12",
        "last_error": null,
        "failures": 0,
        "held": null
      },
      {
        "kind": "update",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "email": "rui@acme.test",
        "fields": [
          "title",
          "groups"
        ],
        "waiting_for_confirm": false,
        "start_date": null,
        "last_error": null,
        "failures": 0,
        "held": null
      }
    ],
    "accounts": [
      {
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "email": "rui@acme.test",
        "status": "ACTIVE",
        "linked": true,
        "excluded": false,
        "admin": false,
        "created_by_bizisy": false,
        "last_error": null,
        "failures": 0
      }
    ]
  }
}

Confirm an Okta change that waits#

POST/v1/org/okta.confirmWrite

Confirms a change that waits for a person (org_okta_preview waiting_for_confirm): create (a new, staged Okta account for someone starting soon), reactivate (a rehire's suspended account), suspend or update (held: new_link, the first change since a link, or many, many suspensions at once: only owners and admins confirm held changes). Bizisy sends it at once. You can't confirm your own account. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. A person confirms new, reactivated and held Okta account changes in the app.
MCP tool
org_okta_confirm on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired
  • kind"create" | "reactivate" | "suspend" | "update"required

Returns

  • person_idstringrequired
  • confirmed"create" | "reactivate" | "suspend" | "update"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/okta.confirm \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p2","kind":"suspend"}'
Response
{
  "data": {
    "person_id": "p1",
    "confirmed": "create"
  }
}

Keep a person out of Okta provisioning#

POST/v1/org/okta.excludeWrite

Excludes a person (excluded true: Bizisy never creates, changes, activates or suspends their Okta account, and forgets the link) or includes them again (Bizisy looks for their account by work email at the next run). Use it for a wrong link too. Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Keeping someone out of Okta provisioning happens in the app.
MCP tool
org_okta_exclude on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired
  • excludedbooleanrequired

Returns

  • person_idstringrequired
  • excludedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/okta.exclude \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1","excluded":true}'
Response
{
  "data": {
    "person_id": "p1",
    "excluded": true
  }
}

Retry an Okta change that failed#

POST/v1/org/okta.retryWrite

Clears a person's Okta failure so Bizisy tries again at once (after 3 failures a change waits for this). Owners, admins and HR, in the app only.

Web app only
Refused for API keys and connected apps. Retrying a failed Okta change happens in the app.
MCP tool
org_okta_retry on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idstringrequired

Returns

  • person_idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/okta.retry \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1"}'
Response
{
  "data": {
    "person_id": "p1"
  }
}

List Okta groups#

POST/v1/org/okta.groupsRead

The Okta groups Bizisy can manage (Okta groups only; groups that come from Active Directory or another app are left out), for mapping teams and job families: id, name. q narrows by name (starts with). Owners and admins.

Who can call it
Manage key owner admin
MCP tool
org_okta_groups on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • qstring

    Up to 100 characters.

Returns

  • groupsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • descriptionstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/okta.groups \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Eng"}'
Response
{
  "data": {
    "groups": [
      {
        "id": "00g1",
        "name": "Engineering",
        "description": null
      }
    ]
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs