Management API
Provision company access from your own server. Preview API v1 is separate from the OIDC client secret and from a user’s private Presence account.
Create a credential
Open Enterprise → People → API. Choose only the needed permissions and an expiry of 1–90 days. Save the secret once in your server secret store. Rotation means create a replacement, update the integration, then revoke the old credential. Credentials stop working when expired, revoked, or their creator loses administrator access.
Requests
Use HTTPS and Authorization: Bearer YOUR_MANAGEMENT_SECRET. Browser origins and cookie-only requests are rejected. GET returns the primary resource list. POST accepts {"operation":"people.create","args":{…}}. Your company is fixed by the credential; it cannot select another company.
curl "$PRESENCE_ORIGIN/api/v1/directory?limit=50" \
-H "Authorization: Bearer $PRESENCE_MANAGEMENT_KEY"
curl "$PRESENCE_ORIGIN/api/v1/directory" \
-H "Authorization: Bearer $PRESENCE_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: staff-create-20261031-001" \
--data '{"operation":"people.create","args":{
"name":"Alex Morgan","email":"alex@example.test"
}}'
Available resources
| Path under /api/v1 | Operations | Scopes |
|---|---|---|
| directory | people.list, people.create, people.update | directory:read / directory:write |
| groups | groups.list, groups.create, groups.update | access:read / access:write |
| access | access.list, access.set, access.revoke, access.evaluate, application.policy, sessions.revoke | access:read / access:write |
| keys | inventory.list, inventory.create, inventory.update | inventory:read / inventory:write |
| diagnostics | diagnostics.list, audit.list | diagnostics:read |
| applications | applications.list | applications:read |
Microsoft Entra ID and Okta via SCIM · SCIM API reference
Changes and retries
Every write needs an Idempotency-Key of 16–100 letters, digits, underscores or hyphens. Repeating the same operation and arguments with that key returns the stored result. Reusing the key with different content returns HTTP 409. Results are replayable for 24 hours. After that, reconcile current state before using a new key.
Update and revoke operations require the current integer revision from the relevant list. A stale revision returns 409: fetch, review and retry, without overwriting someone else’s change. Dates are ISO 8601; future end dates may be at most five years away. Use null to remove an optional end date. People have immutable email identities in this release; an identity correction needs review, not automatic relinking.
Pagination and limits
Lists accept limit (1–100) and offset. Follow nextOffset until null. Directory search accepts a name or email substring; diagnostics support filter=issues and an exact reference. Limits are 120 requests per minute per credential and 240 per source IP, with HTTP 429 and Retry-After. Presence supports 10,000 directory entries per company and 500 people per group. Groups replace the submitted membership set; send the complete intended set.
Errors
Responses contain an error code. 401 means invalid or expired credentials; 403 means missing scope or permissions; 404 means an unavailable company-scoped object; 409 means a duplicate or revision/idempotency conflict. Retry 429 after Retry-After and transient 5xx with bounded backoff using the same idempotency key. Do not retry a denied write blindly.
What this API can change
It manages company directory entries, groups, application assignments, company grants and inventory. It cannot manage company owners, expose private scan material, recover a personal account or enroll a physical Key for someone. Inventory labels are logistical records, not authentication credentials. Marking a company Key lost can suspend the assigned person’s company access. Their owner still revokes their personal Key from Presence.
Revocation contract
A suspension, expiry, assignment withdrawal, application policy change or explicit session revocation invalidates Presence grants. Your website must introspect on protected requests to enforce it. Diagnostic acknowledgement requires the session reporting API; the absence of an acknowledgement is visible. Other valid group assignments may still permit a fresh sign-in.
Preview boundary
SCIM, SAML, outbound webhooks, billing and provider-wide single logout are not available. This is not an OIDC certification or independent penetration-test claim. Use separate credentials and data for Preview and production.
Download the OpenAPI specification · Website setup · Enterprise