Tenant Handling

primaTime is a multi-tenant application where each organization operates as an isolated tenant. Understanding tenant handling is essential for correctly interacting with the API.

What is a Tenant?

A tenant represents an organization in primaTime. Each tenant has:

• Isolated data (projects, clients, tasks, time records, etc.)
• Independent user memberships and permissions
• Separate billing and subscription settings
• Custom organization settings (timezone, currency, branding)

A user can belong to multiple organizations and switch between them.

The X-Tenant-ID Header

For tenant-specific operations, you must include the X-Tenant-ID header:

curl -X POST https://api.next.primatime.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: org_abc123" \
  -d '{"query": "{ projects(first: 10) { edges { node { id title } } } }"}'

Important

The tenant ID in the header must match the tenant ID embedded in your access token. Mismatched tenant IDs will result in an authentication error.

Token Types

Account-Level Token

When you request an access token without a tenant ID, you get an account-level token:

mutation {
  requestAccessToken(data: {}) {
    accessToken
  }
}

Account-level tokens can access:

• User account settings
• List of organizations the user belongs to
• Create new organizations
• Session management

Account-level tokens cannot access tenant-specific data.

Tenant-Level Token

When you request an access token with a tenant ID, you get a tenant-level token:

mutation {
  requestAccessToken(data: { tenantId: "org_abc123" }) {
    accessToken
  }
}

Tenant-level tokens can access:

• All account-level operations
• All data within that specific organization
• Operations are scoped to that tenant's data

Discovering Available Tenants

After login, query your available organizations:

query MyOrganizations {
  authenticationContext {
    accesses(first: 50) {
      edges {
        node {
          id
          organization {
            id
            profile {
              title
              urlPrefix
            }
          }
        }
      }
    }
  }
}

This returns all organizations you have access to.

Switching Tenants

To switch between organizations:

1. Request a new access token for the target tenant
2. Update your Authorization header with the new token
3. Update the X-Tenant-ID header