Skip to content
Udibo

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…CallWith
Sign people in, refresh, and sign outOAuth 2.0 and OpenID Connect endpoints listed in {issuer}/.well-known/openid-configurationYour application's client credentials
Ask whether the signed-in person may actPOST /api/check and POST /api/check/batch on your tenant hostThe person's access token
List the person's organizations or manage them/api/memberships and /api/organizations… on your tenant hostThe person's access token
Show the person's sessions and linked accounts/api/account… on your tenant hostThe person's access token
Read or change who holds a role on one resource/api/resource-grants… on your tenant hostA machine token with a granted permission
Read or manage your tenant's organizations from a backend/api/machine/organizations… on your tenant hostA machine token with a granted permission
Join people to your waitlist from your own form/api/waitlist… and GET /api/signup on your tenant hostA registered origin, or a machine token
Administer the tenant: users, applications, webhooks/api/identity/{tenantId}/… on www.udibo.comThe 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:

Shell
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:

TagPaths on your tenant host
Account/api/account…: the person's record, sessions and linked accounts
AuthorizationPOST /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:

http
RateLimit-Policy: "management";q=100;w=5
RateLimit: "management";r=87;t=1

RateLimit-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.

  1. Register a confidential application with the Client credentials grant. Under Allowed scopes, include Organizations — read. Then create a client secret on its detail page.

  2. On the same page, a tenant Owner or Admin opens Machine permissions, checks Read resource grants, and chooses Save machine permissions.

  3. Request a token from your tenant's issuer, the same issuer your sign-in integration uses:

Shell
curl -X POST "$ISSUER/api/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=identity:organizations:read
  1. Call the API on that same origin with the access_token from the response:

Shell
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) carrying status, title and detail. A 400 that refuses what you sent adds fieldErrors. A 409 conflict can add constraint. Where one status has more than one cause, reason names which one, such as machine_token on a 403. 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 401 with error: "access_denied". An expired or unknown token answers 401 with error: "invalid_token". A token without the operation's scope answers 403 with error: "insufficient_scope" and requiredScope. The message is in detail. On an invalid token or a missing scope, the WWW-Authenticate challenge also carries error and error_description. On your tenant host the challenge names resource_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 a 401 only 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 401 without an error member.

  • 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 for POST /api/waitlist, and 1 MiB for the management API (/api/identity/…). Each operation's 413 in the API reference states its limit. The size is checked before the token or the content, so a 413 says nothing about either.

    • 429 with reason management_rate_limited: the credential has spent its management API budget. See rate limits.

    • 429 from 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.

    • 429 from 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/…, including userinfo, 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 no reason and may have no Retry-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.

    • 429 with reason auth_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's 429, this one is a problem document with a reason and a Retry-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": wait Retry-After seconds, then retry. Refresh an access token by its exp rather than waiting for a 401, because a token expired longer than 15 minutes can get this 429 instead of a 401. 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, 200 or active: false.

    • 400: the content was refused. Content refusals are always 400, never 422.

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.

View Markdown