Copy page

Quickstart

Authentication

The FairePlace API uses API keys for authentication. Each API key is scoped to your organization (tenant) and controls access to all resources within it.

Creating an API key

Generate an API key from the FairePlace dashboard:

1. Log in to FairePlace
2. Go to Paramètres > DÉVELOPPEUR > Clés API
3. Click + Créer une clé API
4. Enter a Name and choose an Expiration (Never, 30 days, 90 days, or 1 year)
5. Click Créer

Important: Copy your API key immediately after creation — it will only be shown once.

Using your API key

Include the API key as a Bearer token in the Authorization header of every request:

Code
curl https://api.faireplace.com/api/places \
  -H "Authorization: Bearer fp_a1b2c3d4e5f6..."

Example with environment variable

Store your key in an environment variable for convenience:

Code
export FAIREPLACE_API_KEY="fp_a1b2c3d4e5f6..."

curl https://api.faireplace.com/api/places \
  -H "Authorization: Bearer $FAIREPLACE_API_KEY"

Node.js

Code
const API_KEY = process.env.FAIREPLACE_API_KEY;

const response = await fetch("https://api.faireplace.com/api/places", {
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
});

const places = await response.json();

Python

Code
import os
import requests

API_KEY = os.environ["FAIREPLACE_API_KEY"]

response = requests.get(
    "https://api.faireplace.com/api/places",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
)

places = response.json()

API key properties

Each API key has the following attributes:

Property	Description
Name	A label to identify the key (e.g. "Production", "CI/CD")
Expiration	When the key expires — Never, 30 days, 90 days, or 1 year from creation
Created at	Timestamp of when the key was generated

Managing API keys

You can view and manage all your API keys from the Clés API page in your dashboard settings:

• View — See the name, creation date, and expiration for each key (the key value itself is only shown once at creation)
• Revoke — Delete a key immediately. Any requests using a revoked key will return 401 Unauthorized

Multi-tenant isolation

FairePlace enforces strict data isolation between organizations:

• Every API key is scoped to your organization's tenant_id
• You can only access resources belonging to your organization
• Cross-tenant access is impossible — the API returns 404 Not Found (not 403) for resources outside your tenant, preventing information leakage

Code
Organization A                            Organization B
┌─────────────────────────────┐         ┌─────────────────────────────┐
│  Places, Estates, Leases    │         │  Places, Estates, Leases    │
│  Tenants, Owners, Contacts  │  ✗───✗  │  Tenants, Owners, Contacts  │
│  Documents, Signatures      │         │  Documents, Signatures      │
└─────────────────────────────┘         └─────────────────────────────┘
       Complete isolation                      Complete isolation

API key lifecycle

Event	Action
Key created	Store securely, use in Authorization header
Key active	Normal API usage
Key expired	Create a new key from the dashboard
Key revoked	Create a new key from the dashboard

API Key lifecycle in detail

Creation

1. Go to Paramètres > Développeur > Clés API in the dashboard
2. Click + Créer une clé API
3. Choose a name and expiration period
4. Copy the key immediately — it is shown only once

Rotation

To rotate a key without downtime:

1. Create a new API key
2. Update your application to use the new key
3. Verify the new key works in production
4. Revoke the old key

Best practice: Schedule key rotation every 90 days for production environments.

Revocation

Revoking a key is immediate and irreversible:

• All in-flight requests using the revoked key will fail with 401
• There is no grace period
• Create a new key before revoking the old one

Permissions

API keys inherit all permissions from the organization. The following permissions control access:

Permission	Read	Write	Description
properties:read	✓		View places, estates, rooms, equipment, keys, meters
properties:write		✓	Create, update, delete properties
leases:read	✓		View leases, charges, documents, amendments
leases:write		✓	Create, update leases and charges
lessees:read	✓		View tenants, contacts, guarantors
lessees:write		✓	Create, update tenants
owners:read	✓		View property owners
owners:write		✓	Create, update owners
signatures:read	✓		View signature status and proofs
signatures:write		✓	Initiate signatures, validate OTP
credits:read	✓		View credit balance and transactions
credits:write		✓	Purchase credits via Stripe
media:read	✓		View and download uploaded files
media:write		✓	Upload photos and documents
compliance:read	✓		Check rent regulation and rent control
types:read	✓		List available types (place, estate, room, equipment)
webhooks:read	✓		View webhook configurations
webhooks:write		✓	Configure webhooks
lessee:leases:read	✓		Tenant-side: view own leases

Note: Permission errors return 403 Forbidden with the required permission in the response body.

Rate limiting per key

Plan	Requests/hour	Burst limit
Free	100	20/min
Starter	1,000	100/min
Pro	10,000	500/min
Enterprise	Custom	Custom

Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per hour
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

When rate limited, implement exponential backoff:

Code
# Check remaining quota
curl -I https://api.faireplace.com/api/health \
  -H "Authorization: Bearer $API_KEY"

# Response headers:
# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 847
# X-RateLimit-Reset: 1708512000

Common authentication errors

401 Unauthorized — Missing or invalid API key

Code
{
  "error": {
    "code": 401,
    "type": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Causes:

• No Authorization header provided
• Malformed or invalid API key
• Expired API key
• Revoked API key

Fix: Check your API key is correct, or create a new one from the dashboard.

403 Forbidden — Insufficient permissions

Code
{
  "error": {
    "code": 403,
    "type": "FORBIDDEN",
    "message": "Permission 'leases:write' required"
  }
}

Causes:

• Your API key doesn't include the required permission for this endpoint

Fix: Contact your organization admin to adjust permissions.

Security best practices

• Never expose API keys in URLs, logs, frontend code, or version control
• Use HTTPS for all API calls (HTTP requests are rejected)
• Set an expiration — avoid "Never" expiration keys in production
• Use separate keys for different environments (development, staging, production)
• Revoke unused keys — delete keys that are no longer needed
• Handle 401 errors gracefully by prompting for a new key or alerting your team