Core Concepts

Copy page

Multi-Tenancy

Understand how FairePlace isolates data between organizations and scopes API access.

How it works

Every API request is scoped to a single organization (tenant) via the JWT token. Data is completely isolated — you can only access resources belonging to your organization.

Code
 
JWT Token → Tenant ID → All queries scoped to this tenant

The tenant ID is embedded in the JWT payload and cannot be modified by the client. Every database query is automatically filtered by tenant.

JWT token structure

Code
 
{
  "sub": "user-uuid",
  "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "permissions": ["properties:read", "properties:write", "leases:read", "leases:write"],
  "iat": 1708425600,
  "exp": 1708512000
}

Claim	Description
sub	User UUID
tenant_id	Organization UUID — determines data scope
permissions	Array of granted permissions
iat	Issued at timestamp
exp	Expiration timestamp

Data isolation

Each tenant has a completely separate dataset:

Resource	Isolation
Places, Estates, Rooms	Per-tenant
Leases, Charges	Per-tenant
Lessees, Owners, Contacts	Per-tenant
Documents, PDFs	Per-tenant
Signatures, Proofs	Per-tenant
Credits, Payments	Per-tenant
Media files	Per-tenant

There is no way to query across tenants. A GET /leases call from Tenant A will never return leases belonging to Tenant B.

Permissions

Permissions are scoped by resource and action:

Permission	Description
properties:read	View places, estates, rooms, equipment
properties:write	Create and update properties
leases:read	View leases, charges, documents
leases:write	Create and update leases
lessees:read	View tenants and contacts
lessees:write	Create and update tenants
signatures:read	View signature status and proofs
signatures:write	Initiate and manage signatures
credits:read	View credit balance and history
credits:write	Purchase credits
media:read	View uploaded files
media:write	Upload files

Permission errors

If you attempt an action without the required permission:

Code
 
{
  "error": {
    "code": 403,
    "type": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": {
      "required": "leases:write",
      "granted": ["leases:read", "properties:read"]
    }
  }
}

Users within a tenant

A tenant can have multiple users, each with different permission sets. User management is handled through the FairePlace dashboard — there is no API endpoint for user management.

Resource ownership

When you create a resource, it is automatically assigned to your tenant. The tenant_id is never exposed in API responses — it's implicit from authentication.

Code
 
# This lease is automatically scoped to your tenant
curl -X POST https://api.faireplace.com/api/leases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estate_id": "...", "lease_type_id": "...", "rent_amount": 950}'

Cross-resource references

All resource references (e.g., estate_id in a lease) must belong to the same tenant. Referencing a resource from another tenant returns a 404:

Code
 
{
  "error": {
    "code": 404,
    "type": "NOT_FOUND",
    "message": "Estate not found",
    "details": {
      "estate_id": "estate-from-another-tenant"
    }
  }
}

---

Related

• Authentication — JWT tokens and login
• Error Handling — Error codes
• Pagination — List endpoint patterns