Tenant resolution: the Host header
The tenant is resolved from the HTTP Host header of the incoming request. Each organization has either a subdomain on orgo.space or a fully custom domain:
The OpenAPI spec lists
https://app.orgo.space as the base URL only because the API playground needs some URL. For real requests, swap that for your tenant’s host.Why this matters for tokens
Tokens are tenant-scoped at the moment they are issued:- Api-Token: tied to the user who created it; that user belongs to one tenant; the token only works against that tenant’s host.
- Session JWT (from
/login-check,/verify-login-otp, a social button or an identity provider): contains asession_idclaim bound to the tenant of the host the login was performed against. A sign-in made on the platform portal can hold a separate session per organization that shares the member’s email, each valid only on its own host. - OAuth access tokens: bound to the tenant where the OAuth application was registered, and capped to member level. See Authentication.
401 Unauthorized; an Api-Token is looked up by its own value, so presenting it to another host finds no usable session there and fails as well.
Cross-tenant access is blocked at the persistence layer
Inside Orgo’s backend, every read and write is automatically restricted to the current tenant before the query runs. Even if a developer wrote a query without a tenant condition, the restriction would be added for them. This is enforced at the ORM level, so no API endpoint can leak across tenants.The one exception: the event app
Members who open an event page of an organization they were invited to, from a different tenant, can switch organizations with an emailed code. The session exchangePOST /api/v1/event-app/session/{tenantSlug} works like this:
- It is only available on the tenant-agnostic host (
app.orgo.space). From a tenant subdomain or custom domain the only legal target is that tenant itself, anything else is refused with403. - A session created by the event app’s own emailed code (
POST /api/v1/event-app/verify-otp) carries anauth_strength: otpclaim and averified_email. That proves the address, so the exchange may target any organization where the address is registered. If the address is not registered there, the exchange is refused with403. - A session that did not come through an emailed code (a password session, say) proves the account but not the address. It can open the event app for the account it is already signed in to, and nothing else.
- A member whose email domain requires the organization’s identity provider gets a token only from a session that came through that provider (see Authentication).
- An emailed-code session is a full login with the same permissions as a password session, so what the exchanged token can do in the target organization is decided by the member’s roles there, not by how the session began.
Resolving your tenant host
An administrator finds the host in the admin UI under Settings → Customization → Custom Domain; see Custom domain. Common shapes:
The default subdomain always works, even when a custom domain is also configured. Use it for integrations to avoid breakage if the administrator changes the custom-domain setup.
What happens when the tenant is missing or wrong
The 404 in the last row is intentional. From outside, “not found” and “exists in another tenant” are indistinguishable, so the response never confirms that a record exists somewhere else. This is the same pattern GitHub uses for private repositories.
Tenant context in webhook deliveries
Webhook payloads carry a top-leveltenant_id field so a single receiver subscribed to multiple tenants can route events. See Webhooks.
Common scenarios
I'm getting 401 errors with a valid-looking token
I'm getting 401 errors with a valid-looking token
Check that the host you are calling matches the tenant the token was issued for. A JWT or OAuth token against the wrong host produces
401, not 403. A wrong or revoked Api-Token produces 404 instead (see Authentication).I want one integration to serve many tenants
I want one integration to serve many tenants
Generate one Api-Token per tenant (each created by an administrator of that tenant) and route by hostname server-side. There is no “super-token” that crosses tenants.
The tenant's administrator changed the custom domain and my integration broke
The tenant's administrator changed the custom domain and my integration broke
Switch to the
*.orgo.space default subdomain. It does not change when the custom domain does.Can I look up a tenant's host programmatically?
Can I look up a tenant's host programmatically?
Yes. Both lookups are public (no authentication needed) and return the tenant’s public profile as JSON-LD, including its
slug and appHost:GET /api/v1/tenant-slug/{slug}finds a tenant by its slug, for exampleacme.GET /api/v1/tenant-host/{host}finds a tenant by a host it is served on, for exampleacme.orgo.space.
404.Related
- Authentication: how tokens carry tenant scope
- Errors: what each tenant-mismatch error looks like

