Mankomail

Authentication ​

Routes are relative to <PUBLIC_BASE_URL>; request and response bodies are JSON unless stated otherwise. Authentication, scopes, pagination and the error format are described in the REST API guides.

POST /api/v1/auth/login ​

Sign in

Opens a session and sets the httpOnly session cookie. Rate-limited per IP before any database read (see Retry-After). A malformed body returns the same code as a wrong password: the route is not an oracle.

Access — No authentication.

Request body (application/json)

FieldTypeRequired
emailstringyes
passwordstringyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "email": { "type": "string" },
    "password": { "type": "string", "minLength": 1, "maxLength": 256 }
  },
  "required": [ "email", "password" ]
}

Responses

200 — The member and the session expiry.

FieldTypeRequired
memberobjectyes
expiresAtstring (date-time)yes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "email": { "type": "string" },
        "name": { "type": "string" },
        "role": { "type": "string", "enum": [ "member", "admin" ] },
        "status": { "type": "string", "enum": [ "active", "suspended" ] }
      },
      "required": [ "id", "email", "name", "role", "status" ],
      "additionalProperties": false
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [ "member", "expiresAt" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

Error codes — auth.invalid_credentials, auth.too_many_attempts, auth.https_required. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

Example request

json
{ "email": "alice@example.test", "password": "correct horse battery staple" }

Example response (200)

json
{
  "member": {
    "id": "0192f1c2-0000-7000-8000-000000000001",
    "email": "alice@example.test",
    "name": "Alice",
    "role": "admin",
    "status": "active"
  },
  "expiresAt": "2026-10-11T09:00:00.000Z"
}

POST /api/v1/auth/logout ​

Sign out

Revokes the session and clears the cookie. Idempotent: answers 200 even without a session.

Access — Member session only: API keys are refused (api_key.session_required).

Responses

200 — Signed out.

FieldTypeRequired
status"ok"yes
JSON Schema
json
{
  "type": "object",
  "properties": { "status": { "type": "string", "const": "ok" } },
  "required": [ "status" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

GET /api/v1/auth/me ​

Who am I

The signed-in member, the session expiry, the public preferences (locale, display mode, theme) and the join date.

Access — Member session or API key with scope profile:read.

Responses

200 — The current member.

FieldTypeRequired
memberobjectyes
expiresAtstring (date-time)yes
settingsobjectyes
joinedAtstring (date-time)no
JSON Schema
json
{
  "type": "object",
  "properties": {
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "email": { "type": "string" },
        "name": { "type": "string" },
        "role": { "type": "string", "enum": [ "member", "admin" ] },
        "status": { "type": "string", "enum": [ "active", "suspended" ] }
      },
      "required": [ "id", "email", "name", "role", "status" ],
      "additionalProperties": false
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "settings": {
      "default": {},
      "type": "object",
      "properties": {
        "locale": { "type": "string", "enum": [ "fr", "en" ] },
        "theme": { "type": "string", "enum": [ "light", "dark", "system" ] },
        "themeName": { "type": "string", "enum": [ "classic", "meridian", "atelier" ] }
      },
      "additionalProperties": false
    },
    "joinedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [ "member", "expiresAt", "settings" ],
  "additionalProperties": false
}

401 — No valid session or API key (auth.unauthenticated).

403 — Refused: insufficient role (auth.forbidden), missing scope (api_key.scope_missing, details.required names it) or a route closed to API keys (api_key.session_required).

429 — The API key exceeded its rate limit (api_key.rate_limited); Retry-After says when to retry.

POST /api/v1/auth/accept-invitation ​

Accept an invitation

Creates the member and consumes the invitation atomically. Does not open a session: the new member signs in with the password just chosen. Unknown, expired and consumed tokens all return the same code. Rate-limited like sign-in.

Access — No authentication.

Request body (application/json)

FieldTypeRequired
tokenstringyes
namestringyes
passwordstringyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "token": { "type": "string", "minLength": 1, "maxLength": 200 },
    "name": { "type": "string", "minLength": 1, "maxLength": 200 },
    "password": { "type": "string", "minLength": 12, "maxLength": 256 }
  },
  "required": [ "token", "name", "password" ]
}

Responses

201 — The member, created.

FieldTypeRequired
memberobjectyes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "member": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
        },
        "email": { "type": "string" },
        "name": { "type": "string" },
        "role": { "type": "string", "enum": [ "member", "admin" ] },
        "status": { "type": "string", "enum": [ "active", "suspended" ] }
      },
      "required": [ "id", "email", "name", "role", "status" ],
      "additionalProperties": false
    }
  },
  "required": [ "member" ],
  "additionalProperties": false
}

400 — The request does not match its schema.

Error codes — governance.invalid_invitation, governance.member_exists, auth.too_many_attempts. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.

GET /api/v1/invitations/{token} ​

Preview an invitation

Is there a form to show? Returns the masked address, the organisation name and the expiry. Unlike acceptance it distinguishes its refusals: 404 unknown, 410 expired, 409 already accepted. Shares the acceptance rate limit.

Access — No authentication.

Parameters

NameInTypeRequired
tokenpathstringyes

Responses

200 — The invitation, usable.

FieldTypeRequired
emailstringyes
organizationNamestringyes
expiresAtstring (date-time)yes
JSON Schema
json
{
  "type": "object",
  "properties": {
    "email": { "type": "string" },
    "organizationName": { "type": "string" },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    }
  },
  "required": [ "email", "organizationName", "expiresAt" ],
  "additionalProperties": false
}

Error codes — governance.invitation_invalid, governance.invitation_expired, governance.invitation_already_accepted, auth.too_many_attempts. The common codes (request.bad_request, auth.unauthenticated, api_key.scope_missing, api_key.rate_limited…) apply to every route; see Errors.