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_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
connectionobjectrequired5 fields
offeredbooleanrequiredstatus"none" | "connecting" | "connected" | "error" | "removed"requiredlabelstring | nullrequiredconnected_atstring | nullrequiredlast_run_atstring | nullrequired
countsobjectrequired6 fields
linkedintegerrequiredexcludedintegerrequiredadminintegerrequiredpendingintegerrequiredwaiting_for_confirmintegerrequiredfailedintegerrequired
itemsobject[]required9 fields
kind"create" | "update" | "suspend" | "reactivate" | "activate"requiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
emailstringrequiredfieldsstring[]requiredupdate: the fields that differ (given_name, family_name, title, department, manager_id, groups).
waiting_for_confirmbooleanrequiredstart_datestring | nullrequiredlast_errorstring | nullrequiredfailuresintegerrequiredheld"new_link" | "many"requiredWhy 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[]required9 fields
personobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
emailstringrequiredstatusstring | nullrequiredOkta's status when Bizisy last looked: STAGED, PROVISIONED (activation sent), ACTIVE, SUSPENDED, DEPROVISIONED, …; null when no account was found.
linkedbooleanrequiredexcludedbooleanrequiredadminbooleanrequiredAn Okta administrator: Bizisy never changes it.
created_by_bizisybooleanrequiredlast_errorstring | nullrequiredfailuresintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/okta.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/okta.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/okta.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_confirmon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequiredkind"create" | "reactivate" | "suspend" | "update"required
Returns
person_idstringrequiredconfirmed"create" | "reactivate" | "suspend" | "update"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/org/okta.confirm', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p2",
"kind": "suspend"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/okta.confirm",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p2",
"kind": "suspend",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_excludeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequiredexcludedbooleanrequired
Returns
person_idstringrequiredexcludedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/org/okta.exclude', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"excluded": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/okta.exclude",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"excluded": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_retryon HR Assistant- Preview
?dry_run=trueruns 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 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"}'const res = await fetch('https://api.bizisy.com/v1/org/okta.retry', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/okta.retry",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_groupson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 100 characters.
Returns
groupsobject[]required3 fields
idstringrequirednamestringrequireddescriptionstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/okta.groups \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"Eng"}'const res = await fetch('https://api.bizisy.com/v1/org/okta.groups', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "Eng"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/okta.groups",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "Eng",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"groups": [
{
"id": "00g1",
"name": "Engineering",
"description": null
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.