Copy page

Core Concepts

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 API key. Data is completely isolated — you can only access resources belonging to your organization.

Code
API Key → Tenant ID → All queries scoped to this tenant

The tenant ID is linked to your API key and cannot be modified by the client. Every database query is automatically filtered by tenant. Isolation is automatic — there is no need to specify a tenant or organization in your requests.

API Key properties

Each API key has the following properties:

Property	Description
name	Human-readable label for the key (e.g., "Production", "Staging")
prefix	All keys start with fp_* (e.g., fp_live_a1b2c3...)
expiration	Optional expiration date — keys can be set to expire or remain valid until revoked
tenant_id	The organization this key is scoped to — determines which data is accessible

API keys are managed from the FairePlace dashboard under Parametres > Developpeur > Cles API.

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.

Isolation guarantees

• Filtering: Every database query includes WHERE tenant_id = $1 — there is no way to bypass this at the API level
• Cross-tenant access returns 404: If you reference a resource belonging to another tenant, you receive a 404 Not Found (not 403 Forbidden) to prevent information leakage
• No multi-org access per user: A single API key is scoped to exactly one organization. There is no way to access multiple tenants with the same key

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 $API_KEY" \
  -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"
    }
  }
}

Edge cases

• Referencing an ID from another tenant: The API returns 404 Not Found. The response is identical to a genuinely non-existent resource — there is no way to distinguish between the two, by design.
• No cross-tenant data sharing: There is no mechanism to share resources, leases, or any data between organizations. Each tenant is a fully isolated environment.

---

Related

• Authentication — API keys and permissions
• Error Handling — Error codes
• Pagination — List endpoint patterns