Choose the right API
Your application talks to Udibo Identity through a few HTTP surfaces. Most of
them live on your tenant's own host, https://{tenant-id}.udibo.com (your
issuer), and accept tokens your tenant issues. The management API that the
dashboard uses lives on www.udibo.com and does not accept your tenant's tokens
yet.
| You want to… | Call | With |
|---|---|---|
| Sign people in, refresh, and sign out | OAuth 2.0 and OpenID Connect endpoints listed in {issuer}/.well-known/openid-configuration | Your application's client credentials |
| Ask whether the signed-in person may act | POST /api/check and POST /api/check/batch on your tenant host | The person's access token |
| List the person's organizations or manage them | /api/memberships and /api/organizations… on your tenant host | The person's access token |
| Show the person's sessions and linked accounts | /api/account… on your tenant host | The person's access token |
| Read or change who holds a role on one resource | /api/resource-grants… on your tenant host | A machine token with a granted permission |
| Read or manage your tenant's organizations from a backend | /api/machine/organizations… on your tenant host | A machine token with a granted permission |
| Join people to your waitlist from your own form | /api/waitlist… and GET /api/signup on your tenant host | A registered origin, or a machine token |
| Administer the tenant: users, applications, webhooks | /api/identity/{tenantId}/… on www.udibo.com | The dashboard today |
The API reference groups operations by resource. Choose a method and path to inspect that operation's servers, authentication requirements, parameters, request media types, and responses. Full object schemas and examples remain in the linked OpenAPI document. The guides for permissions, organizations, and sessions show each tenant-host API in context.
Find the OpenAPI document
One OpenAPI document describes every API on this page except the OAuth 2.0 and
OpenID Connect endpoints, including the ones on your tenant host. Only www.udibo.com serves it, and it needs no credential:
curl https://www.udibo.com/api/openapi.json/api/openapi serves the same document. Your tenant host does not:
https://{tenant-id}.udibo.com/api/openapi answers 404, like any path that
does not exist there. Fetch the document from www.udibo.com even when every
call you make goes to your tenant host.
The document's top-level servers entry is https://www.udibo.com, which is
where the management API runs. Each tenant-host operation names
https://{tenantId}.udibo.com in its own servers block instead. Set
tenantId to your tenant ID. If your client or code generator reads only the
top-level server, point its base URL at your tenant host for these operations.
The tenant-host operations sit under these tags, which are also the sections of the API reference:
| Tag | Paths on your tenant host |
|---|---|
| Account | /api/account…: the person's record, sessions and linked accounts |
| Authorization | POST /api/check, POST /api/check/batch, GET /api/memberships |
| Organizations in your application | /api/organizations… |
| Organizations for your application's backend | /api/machine/organizations… |
| Resource grants in your application | /api/resource-grants… |
| Waitlist | /api/waitlist… and GET /api/signup |
The Account and Waitlist tags also hold management API operations, which run on
www.udibo.com. An operation's servers block tells the two apart.
The document does not describe the OAuth 2.0 and OpenID Connect endpoints:
authorize, token, userinfo and end session. Your tenant host describes them in
its discovery documents, {issuer}/.well-known/openid-configuration and
{issuer}/.well-known/oauth-authorization-server, where {issuer} is
https://{tenant-id}.udibo.com.
The management API
The management API is the HTTP interface behind the dashboard. It covers tenants, users, applications, webhooks, organizations, roles, permissions and the audit log, each addressed by the tenant it acts on. Guides mention its operations so you know what exists, but today you reach them through the dashboard.
Where it runs
Operations live under https://www.udibo.com/api/identity/{tenantId}/…. The
tenant ID is the one in your dashboard URL,
www.udibo.com/identity/{tenantId}/…, and Settings → General shows it as
Tenant ID with a copy button. On your tenant's own host, every
/api/identity path answers 404.
Which credentials it accepts
The API accepts two credentials, both from Udibo's own sign-in at www.udibo.com:
The dashboard's signed-in session.
An access token issued by Udibo's own sign-in. Its token endpoint is
https://www.udibo.com/api/oauth2/token.
Tokens issued by your own tenant come from a different issuer. That includes
client-credentials tokens for your machine applications, and these paths refuse
them with 401.
A valid credential is not enough on its own. Each operation also checks:
A scope on the token, such as
identity:webhooks:read. The OpenAPI document names the scope for each operation.The caller's access over the tenant in the path. This is the access level or role from the tenant's Team page; see team access. A refused read answers
404, whether you lack access or the tenant does not exist.A person behind every write. Even a client-credentials token issued by Udibo's own sign-in reaches only some reads. A write scope does not change that.
Some scopes are never issued to the client-credentials grant:
identity:users:export, identity:users:impersonate,
identity:webhooks:secret, identity:export:directory and
identity:export:credentials. Operations that need one take a token issued to a
signed-in person through the authorization-code grant. Credential export also
needs an interactive person, never a machine.
There is no self-serve way to get a management API credential for a script or a backend. Tokens from your tenant are refused, as described above, and you cannot register your own application with Udibo's sign-in. For now, do administrative work in the dashboard.
Rate limits
Each management API credential may send a burst of up to 100 requests, and its budget refills at 20 requests a second. The limit is the same on every plan. It is counted per credential:
A person has one budget for all of their requests: the dashboard session and any token issued to them share it, whichever tenant they act on.
A machine application has one budget for its client-credentials tokens.
Another person's or another tenant's traffic never spends your budget.
Every answer to a request whose credential was accepted carries two headers, in the structured form of the IETF rate-limit headers draft:
RateLimit-Policy: "management";q=100;w=5
RateLimit: "management";r=87;t=1RateLimit-Policy names the limit: 100 requests over a 5-second window, which
is 20 a second. In RateLimit, r is how many requests you may send now and
t is the number of seconds until your budget is full again. A request refused
before its credential is checked, such as a 401 or a 413, carries neither.
Past the limit, a request is refused 429 as a problem document with reason
management_rate_limited and a Retry-After header. Wait that many seconds,
then retry. Read r to slow down before you are refused.
Bulk and migration operations are exempt. User import
(/api/identity/{tenantId}/user-imports/…), the directory exports
(GET /api/identity/{tenantId}/export/directory and
GET /api/identity/{tenantId}/users/export) and credential export
(/api/identity/{tenantId}/export/credentials/…) neither spend nor check the
budget, and their answers carry no RateLimit headers. A large import is never
refused by this limit, even while your other requests are. These operations
keep their own limits, which their guides and the API reference state. A
migration out of Udibo takes one export, not a burst of requests:
export.
Call a tenant-host API from your backend
Two APIs on your tenant's own host accept your backend's machine token once a tenant Owner or Admin assigns it a machine permission: resource grants, which reads and changes who holds which of your roles on one resource, and machine organizations, which reads your tenant's organizations, members and invitations. The steps below use resource grants.
Register a confidential application with the Client credentials grant. Under Allowed scopes, include Organizations — read. Then create a client secret on its detail page.
On the same page, a tenant Owner or Admin opens Machine permissions, checks Read resource grants, and chooses Save machine permissions.
Request a token from your tenant's issuer, the same issuer your sign-in integration uses:
curl -X POST "$ISSUER/api/oauth2/token" \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope=identity:organizations:readCall the API on that same origin with the
access_tokenfrom the response:
curl "$ISSUER/api/resource-grants?type=document&id=readme" \
-H "Authorization: Bearer $ACCESS_TOKEN"The permissions guide covers
registering the document type, placing grants and revoking them. To read
organizations instead, check Read organizations in step 2 and call
$ISSUER/api/machine/organizations; the
organizations guide
lists each operation and the permission it needs. For
tenant-host APIs that act for a signed-in person, see
organizations and
sessions.
Paging and errors
Management API lists are cursor-paged. A page holds 20 items by default. A
limit above 100 is lowered to 100. Pass back cursors.next for the following
page.
The error conventions apply to every operation in the API reference, on your
tenant host and on www.udibo.com.
Refusals are problem documents (
application/problem+json) carryingstatus,titleanddetail. A400that refuses what you sent addsfieldErrors. A409conflict can addconstraint. Where one status has more than one cause,reasonnames which one, such asmachine_tokenon a403. Ignore members you do not recognize.Bearer-token failures are problem documents with OAuth error codes. On an operation that requires a bearer token, no token answers
401witherror: "access_denied". An expired or unknown token answers401witherror: "invalid_token". A token without the operation's scope answers403witherror: "insufficient_scope"andrequiredScope. The message is indetail. On an invalid token or a missing scope, theWWW-Authenticatechallenge also carrieserroranderror_description. On your tenant host the challenge namesresource_metadata, where a client finds the authorization server. Two kinds of operation differ:The waitlist operations also accept a call without a token from your own or a registered origin. A call with neither is refused
403, so there a401only ever means the token you sent was not valid.The credential-export download takes its own download token, not a bearer token. A missing download token answers
401without anerrormember.
Size, rate and content are refused with different statuses.
413: the request body is over the operation's byte limit. The limit is 64 KiB for most operations, 512 KiB forPOST /api/waitlist, and 1 MiB for the management API (/api/identity/…). Each operation's413in the API reference states its limit. The size is checked before the token or the content, so a413says nothing about either.429withreasonmanagement_rate_limited: the credential has spent its management API budget. See rate limits.429from an operation's own limit: some operations limit how often you can call them, including the exports, user import and the emails sent to a user.429from Udibo's network edge: an address that sends a very high rate of requests, or many with invalid or expired tokens, can be refused on/api/…, includinguserinfo, for up to a minute. The refusal also applies to that address's requests that carry a valid token. Sign-in and the token endpoint are not refused this way. It comes before Udibo's API and is not a problem document, so it has noreasonand may have noRetry-After. Wait a minute, then retry with backoff. A backend that shares its outgoing address with other people's software can be refused because of their traffic.429withreasonauth_rate_limited, from Udibo's API itself: an address that has recently sent many tokens Udibo cannot accept can be refused on the operations that take a bearer token. These are the tenant-host operations,userinfo, and bearer calls to the management API. Unlike the edge's429, this one is a problem document with areasonand aRetry-After. A token Udibo issued that is still valid, or that expired less than 15 minutes ago, is normally answered as usual. Treat it as "not yet": waitRetry-Afterseconds, then retry. Refresh an access token by itsexprather than waiting for a401, because a token expired longer than 15 minutes can get this429instead of a401. The token, revocation and introspection endpoints never answer this way. Over the limit, a token Udibo has no record of gets the answer an unknown token gets:invalid_grant,200oractive: false.400: the content was refused. Content refusals are always400, never422.
Limits today
No customer credential for the management API. Administer your tenant in the dashboard. Your backend's machine tokens reach only the resource-grants API and, with
identity:waitlist:join, the waitlist API on your tenant's host (see the waitlist guide).Machine tokens never write through it. Every management write requires a person with the matching access.
No per-operation examples here. The generated OpenAPI document is the authority for paths, bodies, and scopes; the reference page lets you inspect one operation at a time.
Next: read the API reference, or set up team access for the people who administer your tenant.
Last verified 2026-11-17.

