Skip to main content
A tenant is an isolated workspace within Tally. It owns subjects, holds access grants, and acts as the identity boundary for all read and write operations. Every API call that touches identity data is scoped to a tenant — either yours as the subject owner, or a counterparty’s as a grantee. This page covers creating tenants, assigning members to roles, inspecting usage, and listing subject ownership records.

​
Create a tenant

POST /v1/tenants Creates a new tenant workspace. When authentication is enabled, the calling principal is automatically added as the tenant_owner.

​
Body parameters

​
tenant_id
string
required
A unique, stable identifier for this tenant. Choose something meaningful to your organization (e.g. acme-corp). Cannot be changed after creation.
​
name
string
required
A human-readable display name (e.g. "Acme Corporation").
​
slug
string
An optional URL-friendly alias for the tenant.

​
Response

201 Created 
{
  "tenant_id": "acme-corp",
  "name": "Acme Corporation",
  "slug": "acme"
}

​
Error responses

StatusCodeMeaning
409conflictA tenant with this tenant_id already exists.

​
Example

curl -X POST https://api.tally.so/v1/tenants \
  -H "Authorization: Bearer $TALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme-corp",
    "name": "Acme Corporation",
    "slug": "acme"
  }'

​
Add or update a member

PUT /v1/tenants/:tenant_id/members/:principal_id Adds a principal to a tenant or updates their existing role. This is an upsert — calling it a second time changes the role in place. Requires at least the tenant_admin role to call.

​
Path parameters

​
tenant_id
string
required
The ID of the tenant.
​
principal_id
string
required
The principal to add or update, formatted as oidc:{issuer}#{sub}. For example: oidc:https://auth.example.com#user_abc123.

​
Body parameters

​
role
string
required
The role to assign. Must be one of the values in the table below.

​
Roles

RoleCapabilities
tenant_readerRead identity snapshots, grants, owners, and accessible subjects. Create webhook subscriptions and refresh requests.
tenant_proposerAll tenant_reader capabilities, plus propose entity state updates.
tenant_editorAll tenant_proposer capabilities, plus apply proposed state updates to produce new snapshots.
tenant_adminAll tenant_editor capabilities, plus manage grants (create, list, revoke), manage tenant members, and view usage statistics.
tenant_ownerFull control. All tenant_admin capabilities. The owning principal accountable for the tenant.

​
Response

200 OK — the membership record. 
{
  "tenant_id": "acme-corp",
  "principal_id": "oidc:https://auth.example.com#user_abc123",
  "api_functional_role": "tenant_editor",
  "status": "active"
}

​
Example

curl -X PUT \
  https://api.tally.so/v1/tenants/acme-corp/members/oidc:https%3A%2F%2Fauth.example.com%23user_abc123 \
  -H "Authorization: Bearer $TALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role": "tenant_editor" }'
URL-encode the principal_id path segment before sending the request — the colon and hash characters must be percent-encoded as %3A and %23 respectively.

​
Get usage statistics

GET /v1/tenants/:tenant_id/usage Returns aggregated usage metrics for your tenant over a configurable time window. Useful for monitoring snapshot write volume and API activity. Requires at least the tenant_admin role.

​
Path parameters

​
tenant_id
string
required
The ID of the tenant.

​
Query parameters

​
from
string (ISO 8601)
Start of the time window (inclusive). Must be provided together with to. Defaults to 30 days before to when omitted.
​
to
string (ISO 8601)
End of the time window (inclusive). Must be provided together with from. Defaults to the current time when omitted.
from and to must be supplied together. Providing one without the other returns 400 Bad Request. The from timestamp must not be later than to.

​
Response

200 OK 
{
  "tenant_id": "acme-corp",
  "window": {
    "from": "2024-05-01T00:00:00.000Z",
    "to": "2024-05-31T23:59:59.999Z"
  },
  "usage": [
    { "date": "2024-05-15", "snapshot_writes": 42 },
    { "date": "2024-05-16", "snapshot_writes": 17 }
  ]
}

​
Example

curl "https://api.tally.so/v1/tenants/acme-corp/usage?from=2024-05-01T00:00:00Z&to=2024-05-31T23:59:59Z" \
  -H "Authorization: Bearer $TALLY_TOKEN"

​
List subject owners

GET /v1/tenants/:tenant_id/subjects/:subject_type/:subject_id/owners Returns the owning tenant record for a subject. Every subject has exactly one owning tenant — the tenant that submitted the subject’s first snapshot. This endpoint lets you confirm ownership before attempting write operations. Requires at least the tenant_reader role.

​
Path parameters

​
tenant_id
string
required
The ID of the requesting tenant.
​
subject_type
string
required
Must be entity or individual.
​
subject_id
string
required
The identifier of the subject.

​
Response

200 OK 
{
  "items": [
    {
      "owner_tenant_id": "acme-corp",
      "subject_type": "entity",
      "subject_id": "ent_7f3a1b2c",
      "created_at": "2024-01-10T08:30:00.000Z"
    }
  ]
}

​
Example

curl "https://api.tally.so/v1/tenants/acme-corp/subjects/entity/ent_7f3a1b2c/owners" \
  -H "Authorization: Bearer $TALLY_TOKEN"