> ## Documentation Index
> Fetch the complete documentation index at: https://api.docs.originone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenants

> Act in your child tenants with your own API token.

A tenant's (previously known as reseller) API token can act in its child tenants: read their companies, locations, packages, services, and clinics, search their clinics, and create, read, list, and cancel their orders, with the same token and scopes. This applies to `/api/v2` only.

## Which tenants a token reaches

Each token has a child tenant access setting. It grants none of your child tenants, the ones chosen for the token, or all of them, including child tenants added later. A token reaches none until access is granted.

An admin of your tenant sets it in the **Resellers** field of each token under **Settings → API Tokens**; if the field isn't there, contact Origin One.

A token reaches only **direct** children of its own tenant that are active. A child's own children are never reachable.

List the tenants your token reaches with [List tenants](https://api.docs.originone.ai/api-reference/tenants/list.md), which requires the `tenant.list` scope. The list is empty for a token without child tenant access.

```bash theme={null}
curl https://api.origin.one/api/v2/tenants \
  --header "Authorization: Bearer $ORIGIN_ONE_API_TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "object": "tenant",
      "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
      "name": "Acme Staffing",
      "url": "/api/v2/tenants/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}
```

## Act in a child tenant

To act in a child tenant, prefix the route with `/tenants/{tenantId}`, using an `id` from the list:

```bash theme={null}
curl https://api.origin.one/api/v2/tenants/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11/companies \
  --header "Authorization: Bearer $ORIGIN_ONE_API_TOKEN"
```

A nested route takes the same parameters and body, requires the same scope, and returns the same shapes as its top-level counterpart. These resources have nested routes (paths relative to `/api/v2`):

| Resource | Nested routes |
| - | - |
| Companies | `GET /tenants/{tenantId}/companies`, `GET /tenants/{tenantId}/companies/{id}` |
| Locations | `GET /tenants/{tenantId}/locations`, `GET /tenants/{tenantId}/locations/{id}` |
| Packages | `GET /tenants/{tenantId}/packages`, `GET /tenants/{tenantId}/packages/{id}` |
| Services | `GET /tenants/{tenantId}/services`, `GET /tenants/{tenantId}/services/{id}` |
| Clinics | `GET /tenants/{tenantId}/clinics`, `GET /tenants/{tenantId}/clinics/{id}`, `POST /tenants/{tenantId}/clinics/search` |
| Orders | `POST /tenants/{tenantId}/orders`, `GET /tenants/{tenantId}/orders`, `GET /tenants/{tenantId}/orders/{id}`, `PUT /tenants/{tenantId}/orders/{id}/cancellation` |

Inside a child tenant, the token reaches all of that tenant's active companies, not only the companies linked to the token. Agencies and job categories are the same for every tenant and have no nested routes.

## Each tenant keeps its own records

Each record belongs to one tenant, and only that tenant's routes reach it. Read a child's records through that child's nested routes: the same record requested at the top level, or through another tenant, returns `404 Not Found`.

Records read through a nested route carry a `url` under the same `/api/v2/tenants/{tenantId}` prefix. Agency and job category references are the exception: they keep their top-level `/api/v2/...` url, so a nested order's `agency.url` and `jobCategory.url` have no tenant prefix. Follow `url` as given rather than building paths yourself.

An order created through a nested route sends [webhook](https://api.docs.originone.ai/webhooks.md) events whose `data.url` is under that prefix, so fetching it reads the order inside its tenant:

```json theme={null}
{
  "object": "event",
  "id": "4821",
  "type": "order.updated",
  "createdAt": "2026-10-02T10:00:00.000Z",
  "data": {
    "object": "order",
    "id": "c9b1e2f4-7d3a-4b8e-9f21-5a6c8d0e1b34",
    "code": "CPmJ6QbYMo",
    "url": "/api/v2/tenants/a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11/orders/c9b1e2f4-7d3a-4b8e-9f21-5a6c8d0e1b34"
  }
}
```

If the token loses access to the child, events for its orders keep arriving, and fetching `data.url` returns `404`.

## Tenants outside your reach

A `tenantId` your token does not reach returns `404 Not Found`, the same as one that does not exist. This covers a tenant that is not a direct child, a child the token has no access to, and a child that is deactivated or deleted. The response never reveals whether the tenant exists.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.