# 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](https://www.udibo.com/docs/api) 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](https://www.udibo.com/api/openapi). The guides for [permissions](https://www.udibo.com/docs/identity/permissions), [organizations](https://www.udibo.com/docs/identity/organizations), and [sessions](https://www.udibo.com/docs/identity/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: ```sh 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](https://www.udibo.com/docs/identity/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](https://www.udibo.com/docs/identity/export#limits-on-exports). ## 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: ```sh curl -X POST "$ISSUER/api/oauth2/token" \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=client_credentials \ -d scope=identity:organizations:read ``` 4. Call the API on that same origin with the `access_token` from the response: ```sh curl "$ISSUER/api/resource-grants?type=document&id=readme" \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` The [permissions guide](https://www.udibo.com/docs/identity/permissions) 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](https://www.udibo.com/docs/identity/organizations#read-organizations-from-your-backend) lists each operation and the permission it needs. For tenant-host APIs that act for a signed-in person, see [organizations](https://www.udibo.com/docs/identity/organizations) and [sessions](https://www.udibo.com/docs/identity/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](https://www.udibo.com/docs/identity/apis#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](https://www.udibo.com/docs/identity/waitlist#build-your-own-sign-up-form)). - **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](https://www.udibo.com/docs/api), or set up [team access](https://www.udibo.com/docs/identity/team-access) for the people who administer your tenant. _Last verified 2026-11-17._