Identity Integration API and SDK

Beta

The organization-scoped identity API under /api/integrations/identity, the Rewst-style actions it exposes, authentication, capabilities, idempotency, and the SDK client.

Authentication

Send one of:

  • Authorization: Bearer idc_…, an identity service credential. An organization credential works for its organization; an MSP credential also needs X-Inaya-Organization: <customer id>.
  • A signed-in owner/admin session (the console uses this) with ?orgId=.
  • A signed-in MSP technician session with the customer's ?orgId=, subject to the delegated role.

Every operation is organization-scoped. The organization is never trusted from the client: a session is checked against the caller's own membership or verified MSP delegation, and a credential is bound to its organization. Responses never contain secrets.

Capabilities

Credential scopeCapabilityAllows
identity:readreadProviders (without secrets), users, access, status, metrics, runs, revocations, reports, temporary access, orphans, jobs.
identity:auditauditAudit entries and evidence for a run.
identity:provisionprovisionProvision users, manual overrides (roles/departments/projects), temporary access, retry runs.
identity:revokerevokeRevoke/restrict a person, retry revocations, remediate drift, cancel jobs.
identity:reconcilereconcileReconcile users, post snapshots, pull from Graph.
identity:mappingmappingCreate, change, deactivate mappings.
identity:scimn/aThe SCIM endpoint only.

Providers, credentials, MSP links, access reviews and outbound webhooks are managed by a signed-in owner/admin only. Restoring a revoked person also needs a signed-in owner/admin (or MSP admin).

Endpoints

Paths are under /api/integrations/identity.

Method and pathPurpose (SOW action)
GET/POST /providers, PATCH/DELETE /providers/{id}, POST /providers/{id}/rotate-secret, POST /providers/{id}/pullProviders (getOrganization)
GET /organization, GET /status, GET /metricsgetOrganization, getSyncStatus
GET /users/{email|id}getUser, getMembership
GET /users/by-external?externalId=getUserByExternalId
GET /users/{id}/accessgetAccessibleScope (each grant with its source)
POST /users/provisioncreateUser, updateUser, disableUser (by event.type), with dryRun
POST /users/{id}/revoke (mode: full or restrict)revokeUserAccess, incident restriction
POST /users/{id}/restorerestoreUser (human only)
POST/DELETE /users/{id}/roles, /departments, /projectsassignRole, removeRole, assignDepartment, removeDepartment, assignProject, removeProject
POST /users/{id}/reconcile, POST /users/reconcilereconcileUser
POST /reconcile (snapshot chunk or mode: "graph"), GET /reconcile/reports[/{id}], POST /reconcile/remediatereconcileOrganization
GET/POST/PATCH/DELETE /mappingsMappings
POST /dry-runDry run: text ends with LIVE MUTATION: NO; liveMutation: false
GET /audit, GET /evidence?runId=getAuditEvidence
GET /runs[/{id}], POST /runs/{id}/retry, GET /revocations, POST /revocations/retryLifecycle and revocation
GET/POST /temporary, POST /temporary/{set}/revoke, GET/POST /reviews, POST /reviews/{id}/items/{item}Temporary access, access reviews
GET /orphans, POST /orphans/detect, GET /orphans/manager-analysis, POST /orphans/{id}/resolveOrphans
GET/POST /jobs, POST /jobs/process, POST /jobs/{id}/cancelBulk operations
POST /incident/restrict, POST /incident/restoreSecurity incident containment
GET/POST/DELETE /credentials…, …/msp/…, …/outbound/…Credentials, MSP, outbound events (human admin)
POST /webhooks/{provider id}Signed inbound events (no credential; signature auth). See Security.

The SCIM server is at /api/scim/v2 (see SCIM).

Idempotency and errors

Send Idempotency-Key (8–100 characters) on mutating calls: a repeat returns the recorded response with "replayed": true; reusing a key for a different request is 409. Errors are { "error": "…", "reasonCode": "…" }; reasonCode values include CAPABILITY_MISSING, HUMAN_ADMIN_REQUIRED, ORGANIZATION_NOT_ALLOWED, OWNER_PROTECTED, LAST_OWNER, TENANT_MISMATCH, RATE_LIMITED.

SDK

js
import { IdentityIntegration } from "@inaya-network/custody-sdk";

await IdentityIntegration.sendEvent({ baseUrl, providerId, secret, event });
const r = await IdentityIntegration.disableUser({ baseUrl, credential, organizationId, user: "a@corp.example", reason: "Offboarding 1234", idempotencyKey: "offboard-1234" });
const dry = await IdentityIntegration.dryRun({ baseUrl, credential, providerId, event });   // dry.text

Stateless per-call functions: sendEvent, signWebhook, getUser, getAccessibleScope, provisionUser, disableUser, revokeUserAccess, restoreUser, assign/removeDepartment, assign/removeProject, assign/removeRole, reconcileUser, reconcileOrganization, dryRun, getOrganization, getMembership, getSyncStatus, getAuditEvidence, getAudit.

Last verified 2026-09-26