Mandates

List mandates

Lists the mandates visible to the authenticated user, filtered by their role.

Role filter

The role query parameter controls which mandates are returned:

  • mandataire (default): mandates where the user is the delegate
  • principal: mandates where the user is the principal (the person who granted the mandate)

An empty or missing role is treated as mandataire. Any other value returns 400.

Multi-tenant isolation

Mandates are automatically scoped to the tenant_id extracted from the JWT.

Usage Example

curl -X GET "https://api.faireplace.com/api/mandates?role=mandataire" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "tenant_id": "tenant_123",
    "mandataire_auth_user_id": "user_456",
    "principal": {
      "person_id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "owner",
      "display_name": "Jean Dupont"
    },
    "scope": ["initiate_signature", "sign_on_behalf"],
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31",
    "mandate_document": { "media_id": null, "signed": false },
    "status": "draft",
    "created_at": "2026-01-01T10:00:00Z",
    "updated_at": "2026-01-01T10:00:00Z",
    "revoked_at": null,
    "revoke_reason": null
  }
]
get/mandates

Request

  • Base URL: https://api.faireplace.com/api
  • URL: https://api.faireplace.com/api/mandates
  • Auth: HTTP bearer

Query parameters

role'mandataire' | 'principal'

Filter mandates by the user's role.

  • mandataire (default): user is the delegate
  • principal: user is the principal

Response

List of mandates (empty array if none).

idstring uuid required

Unique mandate identifier.

tenant_idstring required

Tenant identifier (multi-tenant isolation).

mandataire_auth_user_idstring required

Auth user ID of the mandataire (extracted from the JWT).

scopeMandateScope[] required

Ordered list of delegated permissions.

valid_fromstring date required

Start date of validity (ISO 8601, YYYY-MM-DD).

valid_untilstring date nullable

End date of validity (ISO 8601). null means no end date. When set, must be strictly after valid_from.

status'draft' | 'active' | 'revoked' | 'expired' required

Lifecycle status of a mandate.

Valid transitions: draft → active, draft → revoked, active → revoked, active → expired.

created_atstring date-time required

Creation timestamp (ISO 8601).

updated_atstring date-time required

Last update timestamp (ISO 8601).

revoked_atstring date-time nullable

Revocation timestamp, or null if not revoked.

revoke_reasonstring nullable

Free-text reason for revocation (max 500 chars), or null.

Example response

[
  {
    "id": "770e8400-e29b-41d4-a716-446655440222",
    "tenant_id": "tenant_123",
    "mandataire_auth_user_id": "user_456",
    "principal": {
      "person_id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "owner",
      "display_name": "Jean Dupont"
    },
    "scope": [
      "initiate_signature",
      "sign_on_behalf"
    ],
    "valid_from": "2026-01-01",
    "valid_until": "2026-12-31",
    "mandate_document": {
      "media_id": "660e8400-e29b-41d4-a716-446655440111"
    },
    "status": "draft",
    "created_at": "2026-01-01T10:00:00Z",
    "updated_at": "2026-01-01T10:00:00Z"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.