Quickstart

Copy page

Authentication

The FairePlace API uses JWT (JSON Web Tokens) with RS256 signing for authentication and tenant-scoped access control.

Getting a token

Authenticate with your credentials to receive a JWT token:

Code
 
curl -X POST https://api.faireplace.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Code
 
{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRfaWQiOiI1NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDAiLCJwZXJtaXNzaW9ucyI6WyJwcm9wZXJ0aWVzOnJlYWQiLCJwcm9wZXJ0aWVzOndyaXRlIl0sImV4cCI6MTcwOTI5MjAwMH0...",
  "expires_at": "2026-02-20T10:30:00Z",
  "token_type": "Bearer"
}

Using the token

Include the token in the Authorization header of every request:

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

Token contents

The JWT payload contains:

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

• tenant_id — Your organization ID. All API operations are scoped to this tenant.
• permissions — The actions this token can perform.
• exp — Token expiration (Unix timestamp).

Permissions

Permission	Allows
properties:read	List and view places, estates, rooms, equipment
properties:write	Create, update, and delete properties
leases:read	List and view leases, charges, amendments
leases:write	Create, update leases; generate PDFs; manage charges
leases:delete	Delete leases and related resources
lessees:read	List and view tenants and guarantors
lessees:write	Create and update tenant records
lessees:delete	Delete tenant records
owners:read	List and view property owners
owners:write	Create and update owner records
contacts:read	List and view contacts
contacts:write	Create and update contacts
signatures:read	View signature status and proof
signatures:write	Initiate and manage signature workflows
credits:read	View credit balance
credits:write	Purchase credits
media:read	View and download media files
media:write	Upload media files

Multi-tenant isolation

FairePlace enforces strict data isolation between organizations:

• Every request is scoped to the tenant_id embedded in your JWT
• 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
• Database queries are automatically filtered by tenant_id

Code
 
Organization A (tenant_id: aaa-...)     Organization B (tenant_id: bbb-...)
┌─────────────────────────────┐         ┌─────────────────────────────┐
│  Places, Estates, Leases    │         │  Places, Estates, Leases    │
│  Tenants, Owners, Contacts  │  ✗───✗  │  Tenants, Owners, Contacts  │
│  Documents, Signatures      │         │  Documents, Signatures      │
└─────────────────────────────┘         └─────────────────────────────┘
       Complete isolation                      Complete isolation

Token lifecycle

Event	Duration	Action
Token issued	—	Store securely, use in Authorization header
Token active	Up to 24 hours	Normal API usage
Token expired	After exp timestamp	Re-authenticate with POST /auth/login
Token revoked	Immediate	Re-authenticate

Refresh strategy

Tokens are valid for 24 hours. Recommended approach:

1. Store the expires_at value from the login response
2. Before making a request, check if the token expires within the next 5 minutes
3. If so, re-authenticate to get a fresh token
4. Retry the original request with the new token

Code
 
// Example: token refresh logic
function getToken() {
  if (tokenExpiresAt - Date.now() < 5 * 60 * 1000) {
    return refreshToken(); // re-authenticate
  }
  return currentToken;
}

Common authentication errors

401 Unauthorized — Missing or invalid token

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

Causes:

• No Authorization header
• Malformed token (not a valid JWT)
• Expired token (check exp claim)
• Token signed with wrong key

Fix: Re-authenticate with POST /auth/login.

403 Forbidden — Insufficient permissions

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

Causes:

• Your token doesn't include the required permission for this endpoint
• Your user role doesn't have access to this operation

Fix: Request the appropriate permissions from your organization admin.

Security best practices

• Never expose tokens in URLs, logs, or client-side code
• Use HTTPS for all API calls (HTTP requests are rejected)
• Rotate credentials regularly
• Scope permissions to the minimum required for your integration
• Handle 401 errors gracefully by re-authenticating automatically