Skip to main content
Orgo is multi-tenant. Every organization that uses Orgo gets its own isolated workspace: its own users, events, payments, contracts, files. Two organizations cannot see each other’s data, even if a query is misconfigured. This page explains how the API knows which tenant a request is for, and what to do when the answer is wrong.

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:
There is no header, query parameter, or JWT claim that overrides this. The host is the tenant selector.
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 a session_id claim 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.
A token from tenant A cannot be used against tenant B. A JWT or OAuth token trying produces 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 exchange POST /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 with 403.
  • A session created by the event app’s own emailed code (POST /api/v1/event-app/verify-otp) carries an auth_strength: otp claim and a verified_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 with 403.
  • 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-level tenant_id field so a single receiver subscribed to multiple tenants can route events. See Webhooks.

Common scenarios

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).
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.
Switch to the *.orgo.space default subdomain. It does not change when the custom domain does.
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 example acme.
  • GET /api/v1/tenant-host/{host} finds a tenant by a host it is served on, for example acme.orgo.space.
An unknown value returns 404.