Organizations

Use organizations when you sell to companies rather than to individuals. An organization groups your end users, carries their membership tier, and gives you a boundary to scope authority to — so the same person can be an administrator in one customer's account and a read-only member in another's, with one login.

Organizations are optional. A tenant whose product has no notion of "a company" never has to create one; nothing else in the identity service depends on them.

Find your task

For an end-to-end example, follow the B2B SaaS walkthrough. The sections below own the detailed contracts.

The shape

An organization belongs to exactly one tenant. Membership is an edge from the organization to one of your users, never a copy of that user — so a person belongs to as many organizations as you invite them to, keeps one account, and carries a separate tier in each.

Each organization has:

An organization's metadata is confidential from its members, whatever their tier. Your administrators read and write it in the dashboard and through the management API under /api/identity/{tenantId}/organizations. No response a member receives carries it: not the hosted organization pages, not /api/organizations on your tenant's host, and not the organization claims in their tokens. Only your administrators write it, too: POST /api/organizations and PATCH /api/organizations/{organizationId} refuse a body carrying metadata with a 400 and write nothing, so a value there is one only your administrators could have set.

Those two calls refuse any field they do not recognize, not only metadata. Send name and slug alone: an organization you fetched and send back whole, with its id, createdAt, updatedAt or deletedAt, is refused with a 400 and nothing changes.

Organizations are flat. There is no parent organization and no group inside one; sub-teams and organization hierarchies are deliberately not built, and neither is claiming an email domain to auto-join people.

Membership tiers

The three built-in membership tiers are fixed — you cannot rename or remove them — and they inherit downward, so an owner satisfies a check for admin, which satisfies member:

Invitations can also offer a tenant-wide custom role from your role registry. A custom membership role matches only its own slug; it does not satisfy a built-in member, admin or owner check. Accepting that offer does not assign the permissions in the custom role's definition. Assign application access separately through App roles below; an organization-held resource grant can also confer access through accepted membership, as described in permissions and roles.

A tier is not a permission your application reads. It governs the organization's own management surfaces — who may invite, who may remove, who may end the organization. What a member may do inside your product is a role carrying permissions you registered; see permissions and roles.

To assign that application access in the dashboard, open Directory → Organizations → the organization → Members, then choose App roles for a member who has accepted. The assignment page names the organization so you can distinguish this access from tenant-wide roles. Follow assign a role for the steps and required authority. Your customers can manage access through screens you build with the caller-relative API below.

A membership is addressed by the triple of organization, tier and person, and those three are set when the membership is created and never patched. Changing someone's tier means removing the one they hold and offering the new one.

Creating an organization

Your application creates one for its signed-in user — build this. From inside your own product, POST https://{your-tenant-host}/api/organizations with that person's own access token makes the organization and their accepted owner membership in one write. It takes no identity:* scope and no dashboard credential — see organizations inside your own application below. This is the path to put a self-serve B2B product on: the first person from a company signs up, creates their company on a screen you own, and invites their colleagues.

You create one for them. In your dashboard, Directory → Organizations → Create organization. The management API operations are listed for reference; see the note under the administrator's API:

Deleting an organization is a soft delete that frees its slug for reuse immediately — but only once the organization holds nothing. The delete is refused, 409, while the organization holds a live resource grant — a role you granted it on one of your resources. The refusal names those resources, up to three of them, so a DELETE that comes back 409 tells you which grants to deal with rather than leaving you to hunt for them.

A grant whose role definition you have since retired does not block the delete. It confers nothing while the role is retired and does not list on the resource either, so there would be nothing to revoke and no way out of the refusal.

The guard exists because a soft delete would otherwise take its members' access with it silently. Anything they reach through the organization — a resource your application granted the organization as a whole — resolves only through a live organization, so the moment the row is soft-deleted every member stops resolving on their very next request, and the grant row itself survives pointing at nothing. Refusing the delete puts that decision in front of the administrator instead of behind them.

So the order is yours to choose, deliberately:

• Move the access. Grant the same role to another organization, or to the individual users who need it, and then delete.

• Revoke it. Take the grants away with POST /api/identity/{tenantId}/resource-grants/revoke, then delete.

Members are still left alone by the delete itself: their memberships reference an organization that no longer resolves, which every read already filters on. And the delete stays soft, so the row survives for the audit trail — but no surface brings a deleted organization back today, so treat it as final.

Who may create organizations

By default every signed-in user of your tenant may create an organization from your application through POST /api/organizations. A tenant can close that: in your dashboard, Tenant → Settings → General → Organizations, set Who may create organizations to Only your team. The field is also a management API setting, listed for reference:

• anyone — every signed-in end user of the tenant may create an organization and becomes its owner: the posture every tenant has until it chooses otherwise.

• none — only your administrators create organizations. The self-serve create is refused on every surface identically: the API answers 403 with reason: organization_creation_disabled and writes nothing, and on Udibo's own host — the only host that serves them — the /organizations/new page explains instead of offering the form and the /organizations list drops its create button. The action behind the page refuses on its own, so hiding the form is not what keeps people out.

• You are never governed by it. Creating an organization for your users from the dashboard or through POST /api/identity/{tenantId}/organizations works whatever the setting.

• Organizations that already exist, their members, invitations and roles are untouched. This is a switch on who starts a new organization, not a limit on how many there are — organizations stay unlimited on every plan.

• Send { "organizationPolicy": { "creation": "none" } } in the PATCH body. Like the other policy objects it merges, so a switch you omit keeps its value; a value outside the two answers 400 naming organizationPolicy.creation.

Inviting members

Two surfaces make the offer, and both write the same rows and the same audit events:

• Your application, acting as an owner or admin signed in to it — build this. POST https://{your-tenant-host}/api/organizations/{organizationId}/invitations with that person's own access token, described in organizations inside your own application.

• You, in the dashboard under Directory → Organizations.

An offer names an email address and a tier or role:

{ "email": "ada@example.com", "role": "admin" }

The address decides what happens next, and the caller does not choose:

• The address already has an account in your tenant. The offer is written straight to a pending membership, waiting for that person to accept.

• The address has no account yet. The offer is stored as an invitation against the address alone, and waits until someone signs up and verifies it.

The response says which happened, so your own UI can say the right thing. Offering the same address the same role twice is refused as a conflict rather than creating a second offer.

Only the second branch expires. An invitation written against an address with no account is acceptable for 7 days. A pending membership — the branch taken when the address already has an account — carries no expiry at all and waits indefinitely. Either way you withdraw one by deleting it, which frees the address to be offered that role again.

Accepting is bound to the person, never to the link

An id is not a capability on either branch, which is what makes an invitation link safe to hand out: one that reaches the wrong person buys them nothing. What each branch binds to differs, and it is worth knowing which you are handling:

• An invitation converts only for a session whose user holds the invited address and has verified it, and only before it expires.

• A pending membership converts only for the session of the person it was written for — it is claimed by user id, so the email is not re-checked at acceptance and an unverified address does not stop it.

Invitees accept on your tenant's own host at /organization-invite, where the offers waiting for them are listed — or inside your own application, once you have given your tenant a home URL and built the landing page described under rendering the invitation landing in your application.

The emailed link opens that one invitation. Its invitee sees who invited them (the inviter's name, when a person of your tenant sent it), the organization, the role, and when it expires, with Accept invitation and Decline. Both are plain forms, so the page works without JavaScript. Once the invitation can no longer be accepted, the page says why instead: it has expired, it was already accepted or declined, the organization withdrew it, or the organization no longer exists. The page describes an invitation only to the person it was sent to:

• Signed in as a different account, the page says only that the invitation is for someone else, names nothing about it, and offers Switch account, which signs them out and back in and returns them to the same invitation.

• Signed in with the invited address unverified, it asks them to verify the address first and names nothing about it.

• Signed out, they go to your sign-in page and come back to the invitation afterwards, including through creating an account, verifying its address, or resetting a forgotten password.

Declining is the invitee's own decision and is audited as theirs. It frees the address to be invited to that role again, and an invitee who declines twice changes nothing the second time. A declined invitation is recorded as admin.organization.invitation.declined, and a declined pending membership as admin.organization.member.declined, each attributed to the invitee; a webhook subscribed to them receives them like any other event. Nobody is emailed. Declining is available on the hosted invitation page only: the offers API lists and accepts offers but has no decline.

We email the invitee on both branches. Creating an offer queues one message to the address it names, linking /organization-invite on your tenant's own host with that offer already selected — or your application's home URL carrying the offer's id, when you have set one. It goes out under your tenant's branding, through your tenant's own sender, and counts against the same email allowance as the rest of your mail. It carries no token — the id in the link is not a capability on either branch — so the message is safe to forward and worthless to intercept.

What it says splits the same way the offer does, because what the recipient has to do differs:

• An address with no account is told to create one on that address, verify it, and then accept, and the message names the 7-day deadline.

• An address that already has an account is told to sign in and accept. That message promises no deadline, because a pending membership has none.

Delivery does not gate the offer, and the response says nothing about it. The offer is written, returned to you, and listed to the invitee whether or not the message goes out — a send that fails costs a notification, not an invitation. If you need to be certain a person was told, send your own message too; what the offer wrote comes back to you in the response.

Three things suppress the mail while leaving the offer standing:

• An address on your tenant's suppression list (a hard bounce or a spam complaint) is not mailed.

• One inviter may cause at most 20 invitation emails an hour, across every address and every organization. This is a ceiling on volume, not on invitations: past it the memberships and invitations are still written and still listed, and only the mail is dropped. Invite a team larger than that in one sitting and some of them will not hear from us — tell those people yourself, or spread the invitations out.

• One address is mailed at most 5 times an hour per organization. The budget is per organization on purpose: it bounds a repeated invite-and-withdraw loop against one inbox without letting one organization's sends silence another organization's invitation to the same person.

Invitations do not open a closed door. If your tenant's sign-up mode is closed or waitlisted, an invitee who has no account still cannot create one — an organization invitation is not a sign-up admission, and only a waitlist invitation is. Invite people who already have accounts, or admit them through the waitlist first.

Removing a member

Removing is per membership, not per person: a member holding two roles in one organization has two memberships, and removing one leaves the other. The last accepted owner cannot be removed, so an organization is never ownerless.

Removing someone's last membership removes them, and ends what membership gave them there. In the same step, Udibo:

• takes away every application role granted to them inside that organization (their tenant-wide roles and their grants on individual resources stay);

• withdraws every offer still open to them there — pending memberships, and invitations to their address — including an owner offer the person removing them could not have withdrawn themselves.

Each of these is recorded in the audit log as its own event — an application role as admin.user.role_revoked, a withdrawn offer as admin.organization.member.revoked or admin.organization.invitation.revoked — naming who removed them and carrying reason: "membership_ended". If they are invited back later, they hold only what the new invitation offers; grant any application role again after they accept.

Bringing people back to your application

The one page your users act on — accept at /organization-invite — takes a return_to, so somebody you send there lands back in your product instead of finishing on our page and having to find their own way home:

https://{your-tenant-host}/organization-invite?return_to=https%3A%2F%2Fapp.example.com%2Fteams

Where it may point is your own registered redirect URIs. An absolute URL is accepted only when its origin — scheme, host and port together — is the origin of a redirect URI you registered on one of your live applications. Any path on that origin is fine; it does not have to be the callback itself. The allowlist is deliberately that list and no other: an origin you registered already receives this tenant's authorization codes, so sending a person there grants nothing that registering it did not. A path on your tenant's own host (/organizations, say) is accepted too.

Four registrations do not qualify an origin, each for the reason sign-in already ignores it:

• A wildcard registration (https://preview-*.example.com/callback) names no single origin.

• A callback on an application you have deleted.

• A plaintext http:// callback on a production application, which sign-in does not honour either.

• A different port on a host you registered. The port is part of the origin.

A return_to we do not accept is dropped, not refused. The person is never shown an error and never stopped mid-flow: they finish exactly where they would have without the parameter — your tenant's home, per the landing order below — with the outcome appended. A value we rejected is never written back into the page either, so a crafted one cannot be reflected at whoever opens the link.

It survives signing in. Somebody who follows one of these links signed out goes through sign-in and comes back to the page with the parameter intact, and an acceptance that needs authentication carries it through the same round trip.

An invitation your application makes can carry one too. Put return_to in the body of POST /api/organizations/{organizationId}/invitations and the invitee is brought back to your application after accepting, with the outcome appended as above. Because an API caller can act on a refusal where a person mid-flow cannot, this one is validated when you write it against the same allowlist and refused with a 400 naming return_to in fieldErrors rather than dropped — an offer never stores a destination we would not honour. The accepted value is kept on the offer and put in the emailed link, and it is checked again when the invitation is accepted: delete the application whose origin it named in between, and the invitee lands on the ordinary fallback instead.

We say what happened in the query when we hand the person back: organization-invite=<accepted|invalid|expired|wrong-account>.

Where an accepted invitation lands when nothing asked for the person back

A return_to names where a specific request should end. Most invitees carry none — they followed an email — so the tenant needs a standing answer, and it has two. Set a home URL under Settings → Branding, or as branding.homeUrl on PATCH /api/identity/tenants/{id} (the same rule applies on both, and the API reference documents the other branding fields): your own application, where a signed-in person goes when nothing asked for them back. It is accepted only when it is on the origin of a redirect URI registered on one of your live applications — the same allowlist return_to runs — and refused otherwise, so it can never be an open redirect; it is checked again each time it is used, so deleting that application makes us fall back rather than keep sending people there. Leave it blank and we guess: the origin of your oldest first-party application with a registered redirect URI.

The destination is consulted in this order, and the first that answers wins:

1. The request's own validated return_to.

2. Your home URL.

3. The origin of your oldest registered first-party application.

4. /profile on your tenant's host, when you have registered nothing at all.

Every one but the last has the outcome appended (organization-invite=<status>). The same home is where a sign-in on your tenant's host lands when it named no continuation, and where the "Back to {name}" button on our hosted account pages points. It does not change where a support impersonation session lands: your first-party application's origin, or a status page when there is none.

The active organization

A credential we issue acts in one organization at a time — the active one. That is what lets your application ask "may they do this here" without you threading an organization id through every call.

• One membership auto-selects. Someone who belongs to exactly one organization never has to pick; it is resolved on every issuance, never written back.

• Two or more select nothing until the person chooses, and the choice is made from your application — on the authorization request or the refresh grant, as below. A person may also act with no organization at all.

• Your application can name one. Add organization to the authorization request — the organization's id or its slug — and the sign-in lands already acting there. It scopes this credential and nothing else: the browser session's own pick is untouched, so another application signing in on the same browser session gets what the person picked, not what your link named.

• Which organization a credential gets, in order. The one your request names; else the one the person picked on our switcher, where picking Personal means none; else, for someone in exactly one organization who has picked nothing, that one. A sign-in link is a GET any page can start, so no request of yours moves the pick that outlives one credential — only the switcher does, from a same-origin form. The switcher (/organizations) serves Udibo's own site only and a customer tenant's host redirects it there, so for your users the order is in practice the organization your request names, then their sole membership.

GET https://{your-tenant-host}/api/oauth2/authorize?…&organization=acme

To move an existing credential to another organization without sending the person back through sign-in, name it on a refresh request. Here it must be the organization's id — the refresh grant does not accept a slug:

async function tokenForOrganization(
  host: string,
  clientId: string,
  refreshToken: string,
  organizationId: string,
): Promise<{ access_token: string; refresh_token: string }> {
  const response = await fetch(`https://${host}/api/oauth2/token`, {
    method: "POST",
    headers: { "content-type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: clientId,
      refresh_token: refreshToken,
      organization_id: organizationId,
    }),
  });
  if (!response.ok) {
    throw new Error(`token request failed: ${response.status}`);
  }
  return await response.json() as {
    access_token: string;
    refresh_token: string;
  };
}

The request above authenticates as a public client. A confidential client sends its client_secret the same way it does on any other refresh.

organization_id is accepted on the refresh grant and nowhere else — sending it on any other grant is an invalid_request.

An unavailable organization refuses the exchange before anything rotates — whichever access-token format your application is configured for, and whether or not it requests the openid scope. The refresh token you presented is still good, so a retry without the parameter succeeds and the credential keeps the organization it already had. Confirm the organization is one the person belongs to — /api/memberships lists exactly those — before naming it.

The refusal is about the organization this request names. One the credential already carries that stops resolving — a membership revoked since the switch — does not refuse: the credential carries no organization from then on, so its organization claims drop rather than moving to another organization, and its refresh loop keeps working.

Every way an organization can be unavailable answers the same. Unknown, another tenant's, deleted, never a member, membership revoked — one refusal for all five, down to not echoing the id back, so probing cannot tell a tenant's organizations apart from ones that never existed. Expect the refusal, not a reason you can branch on.

What your application reads

The organization on the credential

The active organization reaches your application as three claims:

All three are stamped on the UserInfo response, the introspection response, and — for applications configured for JWT access tokens — the access token itself. The id_token carries org_id and org_slug but not org_roles: roles are authorization, which the id_token leaves out so its size stays bounded, so read org_roles from introspection or UserInfo. Earlier releases put org_roles in the id_token too. Every surface runs the same resolution, so the claims mean the same thing wherever you read them. The organization's display name is deliberately not a claim: it changes, and a token is the wrong place to cache it. Read it from /api/memberships.

Every surface answers for the same organization, for the whole life of the credential. The organization is resolved once, when the credential is issued, and recorded on it: the id_token and a JWT access token carry that resolution in their signed bytes, and the introspection and UserInfo responses re-validate that organization on every call rather than re-deciding which organization it is. Introspecting the family's refresh token answers the same way. So switching organizations changes what the next credential is minted for and leaves an outstanding one alone, and a gateway that routes on org_id from the JWT while the service behind it authorizes on permissions from introspection is reading one organization on both sides.

All three are absent when no organization is active, and each is re-derived from live rows — at every issuance, and again on every introspection and UserInfo response — so a deleted organization or a revoked membership never leaves a stale organization on those two surfaces. Only what was already signed into an id_token or a JWT access token keeps what it was minted with until that credential expires or refreshes. When the credential's own organization stops resolving — deleted, or the membership revoked — introspection and UserInfo drop the organization claims rather than answering for whichever organization the login session has since picked, and the permissions they return narrow to what the subject holds tenant-wide. A revoked membership reads as "no organization", never as a different one.

Do not confuse org_roles with the separate roles claim, which carries the tenant-wide role slugs a subject holds everywhere. Mixing them would apply an organization's roles outside it.

The memberships the caller belongs to

Tokens deliberately carry the active organization, not the whole list. When you need the list — to render a switcher of your own — ask for it with the person's own access token, on your tenant's own host:

interface Membership {
  org_id: string;
  org_slug: string;
  name: string;
  roles: string[];
}

async function memberships(
  host: string,
  accessToken: string,
): Promise<Membership[]> {
  const found: Membership[] = [];
  let cursor: string | null = null;
  do {
    const url = new URL("/api/memberships", `https://${host}`);
    if (cursor) url.searchParams.set("cursor", cursor);
    const response = await fetch(url, {
      headers: { authorization: `Bearer ${accessToken}` },
    });
    if (!response.ok) {
      throw new Error(`memberships failed: ${response.status}`);
    }
    const page = await response.json() as {
      memberships: Membership[];
      cursor: string | null;
    };
    found.push(...page.memberships);
    cursor = page.cursor;
  } while (cursor);
  return found;
}

It answers for the caller and only the caller: there is no field naming somebody else, it needs no scope, and a machine (client_credentials) credential is refused — it holds no memberships. Accepted memberships only, up to 100 per page.

roles lists what is held, not what it implies. The tiers inherit when we resolve a check, but this array is unexpanded — an owner comes back as ["owner"] alone. A reader that asks roles.includes("admin") therefore denies the owner; compare against every tier that satisfies you, or ask /api/check and let the resolution do it.

Whether they may act here

The permissions claim on the credential already answers for the active organization, and on an introspection or UserInfo response it answers as of now. For any other organization — or a live answer for a reader holding a JWT access token, whose claims were fixed when it was signed — ask directly:

async function mayActInOrganization(
  host: string,
  accessToken: string,
  organizationId: string,
  permission: string,
): Promise<boolean> {
  const response = await fetch(`https://${host}/api/check`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${accessToken}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      permissions: permission,
      resource: { type: "organization", id: organizationId },
    }),
  });
  if (!response.ok) throw new Error(`check failed: ${response.status}`);
  const { results } = await response.json() as {
    results: Record<string, boolean>;
  };
  return results[permission] === true;
}

Permissions and roles covers the whole model — registering the capability strings, composing them into roles, and the three widths an assignment can have.

Roles inside an organization

An organization has its own role vocabulary, separate from the membership tiers above. Roles defined for the whole tenant can be held anywhere in it; roles defined on one organization's page apply only there, and the organization's own owner or admin composes them from the permissions you registered.

Both kinds resolve into the same permissions claim, so your application never has to know which kind someone holds. The slugs owner, admin and member are reserved for the built-in membership tiers. Other customer role slugs, including support, do not confer Udibo dashboard authority; dashboard access remains separate from application roles.

Manage the tenant-wide vocabulary in your dashboard under Access control → Roles, or through /api/identity/{tenantId}/organization-roles; an organization's own roles live under the Roles tab on its page.

Organizations inside your own application

Everything your users do with an organization, your application does for them from inside your own product. The surface is on your tenant's own host:

https://{your-tenant-host}/api/organizations

It is the same organization surface the dashboard drives — the same service calls, so the rows and the audit events are identical however the write arrives. There is no hosted organization page on your tenant's host to fall back on: /organizations and everything beneath it redirect to Udibo's own site there, so your users create, switch, invite and manage from screens you own, and meet a page of ours only to accept an invitation.

It exists only on your tenant's own host. On Udibo's own host every one of these paths answers 404. The /api/identity/… endpoints are the separate administrator surface described below; do not point your application at those.

The credential is the signed-in person's own access token, issued by your tenant's authorization server — the same token your application already sends to /api/memberships and /api/check. No identity:* scope is required, and no dashboard access: a customer's end user holds neither and never will. Neither substitutes for authority either. What a caller may do is decided on every request by that caller's own accepted membership, so holding a scope changes nothing. A token your tenant did not issue, or no token at all, is a 401.

A machine (client_credentials) token is refused 403 on every verb, including create. A machine credential acts for an application rather than for a person, so it holds no memberships and there is nobody for it to act as. The refusal is the same on every path and lands before any organization is looked up, so it never tells you anything about an organization. Call this API with a person's token, and only with that.

What you can call, and what it takes

The three tiers of the membership ladder are the whole authority model here — never a scope, never a seat, never anything your application asserts about the caller:

• Listing your own organizations and creating one need only a signed-in person. The creator becomes the new organization's accepted owner in the same transaction, so there is never an organization nobody manages.

• Any accepted membership reads the organization and its member list. The organization comes back without its metadata, whatever the caller's tier; see the shape.

• An accepted owner or admin does everything else: rename, invite, withdraw an invitation, revoke a membership, and define, edit or retire the organization's own roles. Reading the invitation list, the invitation vocabulary (member-roles) and the organization's roles is manager-only too.

• An owner deletes the organization, and is also required to offer or revoke the owner role itself.

Granting a member who has already accepted an application role — a tenant-wide one, or one of this organization's own — through members/{userId}/roles is manager-only too and takes effect without another invitation. A pending member, a non-member and a role this organization cannot see all answer the same 404, and revoking a built-in role held here additionally requires holding at least that rank here. The ids the grant takes come from two reads: member-roles names each tenant-wide role's id beside its slug and name (the built-in tiers carry no id, because they are constants rather than rows), and GET …/roles lists this organization's own. GET …/members/{userId}/roles answers the application roles a member holds here — each with its id, slug, name, permissions and, for one of this organization's own roles, its organizationId — so a screen can show what it would revoke. It is manager-only like the grant, and a pending member, a non-member and an unknown id answer the same 404 the grant does.

Two rules carry over from the surfaces you already know, because it is the same code underneath: a delete is refused 409 while the organization still holds a live grant, and a role may only carry permissions your tenant has registered — an unregistered key is refused 400, naming each offending entry by index. Renaming a role is refused 409 while a grant still holds it, exactly as retiring it is.

Below the read tier there is one refusal, byte for byte. A malformed id, an unknown one, one belonging to another tenant, a deleted organization and one the caller simply is not a member of all answer the same 404, so this API cannot be used to learn which organizations exist. There is no reason in it to branch on. Only where the caller is already a known manager and the tier is the one thing missing is the refusal a 403 that says so: an admin deleting the organization, and an admin offering or revoking the owner role.

Nothing in the request names a tenant. The host does. A tenantId in the body or the query string is dropped rather than honoured, and the write lands in the tenant whose host you called.

Calling it from the browser

These endpoints answer any origin — Access-Control-Allow-Origin: *, and Access-Control-Allow-Credentials is never sent. That is safe here for one reason: no cookie authenticates anything on this surface. The only credential read is the Authorization header your own code attaches to that one request, so a wildcard hands another page nothing it could not already send for itself. A request carrying your tenant's session cookie and no bearer token is a 401.

What a browser in your application sends:

• Authorization: Bearer <the person's access token> on every request.

• Content-Type: application/json on a write. That makes it a preflighted request; the OPTIONS is answered before authentication, because a preflight carries no credential to authenticate.

• Not credentials: "include". It buys nothing — no cookie is read, and without Access-Control-Allow-Credentials the browser would refuse to expose the response to you anyway.

export async function createOrganization(
  host: string,
  accessToken: string,
  input: { name: string; slug: string },
): Promise<{ id: string; slug: string; name: string }> {
  const response = await fetch(`https://${host}/api/organizations`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${accessToken}`,
      "content-type": "application/json",
    },
    body: JSON.stringify(input),
  });
  if (response.status !== 201) {
    throw new Error(`create organization failed: ${response.status}`);
  }
  return await response.json() as { id: string; slug: string; name: string };
}

An invitation posted here behaves exactly as inviting members describes: the address decides whether a pending membership or a pre-subject invitation is written, the response says which, and the invitee is emailed either way. Accepting is the invitee's own call, made with their own token — through our hosted /organization-invite page, or through the two offer verbs below from a landing page you build.

Rendering the invitation landing in your application

By default the invitation email opens our hosted /organization-invite page on your tenant's host. Give your tenant a home URL (Settings → Branding, or branding.homeUrl on PATCH /api/identity/tenants/{id}) and the email opens your application instead, so the invitee never leaves your product:

{homeUrl}?organization-invite=<offerId>
{homeUrl}?organization-invite=<offerId>&return_to=<the inviter's return_to>

The page at that URL is yours to build, and it needs three things:

1. Read organization-invite off the query. A uuid is an offer to accept. Anything else (accepted, invalid, expired, wrong-account) is an outcome our hosted page is reporting back to you — someone used the hosted page with no return_to, and it landed on your home URL as described above — so show the result and stop.

2. Sign the person in, then list what is waiting for them: GET /api/organizations/offers with their access token. It answers exactly what the hosted page lists — invitations to the caller's verified email address plus the pending grants they are the subject of, each with its organization's name and a readable role — and unverifiedEmail names the caller's address while it is unverified, in which case invitations to it are hidden until they verify it. An offer whose organization has since been deleted is omitted.

3. Accept the one the link named: POST /api/organizations/offers/{offerId}/accept, same token, no body. The answer is always a 200 whose status says what happened:

These are outcomes to show the person, not errors, and the hosted page treats them the same way, so a malformed or unknown id is invalid rather than a 404. Every rule the hosted page enforces holds here, because the API runs the same functions it runs: an invitation converts only for the verified holder of its address, a pending grant only for its own subject, either only into a live organization, and a refused offer is left unspent. Holding the id is never enough. A machine token is refused 403 on both verbs.

return_to on the link is data for you, not an instruction. It is the destination the inviter asked the invitee to end up at, validated against your registered redirect URIs once, when the invitation was made, and carried unchanged. On our hosted page it is checked again at acceptance; on yours it is not — the accept verb never sees it — so treat it as a hint you validate yourself before following (your own origin, or an origin you trust), or ignore it. Never redirect to it unchecked.

The hosted page keeps working with a home URL set: an old email, or a link you build yourself to /organization-invite?id=… on your tenant's host, still opens it.

The administrator's API, and your application's

Two APIs manage organizations, and what separates them is who is calling:

• /api/identity/{tenantId}/… is the administrator's surface — the endpoints listed under creating an organization. They accept only the dashboard's own session or a token from Udibo's own sign-in, which you cannot get outside the dashboard; a token your tenant issues, including a client-credentials token, is refused with 401. Use the dashboard; see the management API.

• /api/organizations on your tenant's own host is your application's surface — the same organizations, acting as the person signed in to your product, authorized by their membership rather than by authority over your tenant. This is the one to build your own organization screens on.

/api/identity/organizations is neither. It is the same caller-relative surface addressed on Udibo's own host, for people signed in to Udibo itself, and it answers 404 on your tenant's host. Your application never calls it.

Your users' own surfaces are unaffected by either: /organization-invite, /api/memberships and /api/check all run on your tenant's own host and authenticate the person's own credential.

Limits today

• Flat only. No nested organizations, no groups inside one, and no domain capture that auto-joins an address.

• No resend button. The invitation email goes out once, when the offer is created. To send another, withdraw the offer and make it again — which mints a new one and a new link, inside the hourly budgets above.

• No delivery reporting. Nothing tells you whether an invitation email was sent, dropped for budget, or bounced; the response is the same either way.

• Nothing accepts an offer on the invitee's behalf. Your application can render the landing page and accept with the invitee's own token, but no administrator or machine credential can accept for them. Where your application renders no landing, the invitee finishes at /organization-invite on your tenant's own host — the one organization page a customer's users meet there; the management pages serve Udibo's own host only.

• A tier or role is never patched onto an existing membership. Remove and re-offer.

• Organizations are not a tenancy boundary. They group your end users inside one tenant; they do not partition your data for you.

Last verified 2026-10-29.