{ "openapi": "3.1.0", "info": { "title": "Cross Events API", "version": "v2", "description": "Version 2 of the Cross Events API. Every response is JSON:\n- a single item is `{ \"data\": { … } }`;\n- a list is `{ \"data\": [ … ], \"meta\": { \"page\", \"limit\", \"total\", \"pages\" } }`, paged with `?page=` and `?limit=` (at most 100);\n- an error is `{ \"error\": { \"code\", \"message\", \"fields\"? } }` with a stable `code`.\n\nDates are ISO 8601 in UTC; amounts are in rand. Sign in through the app and send the token as `Authorization: Bearer `.\nVersion 1 (`/api/…`) keeps working while the app moves over; it will be removed in 2.0." }, "servers": [ { "url": "/api/v2" } ], "tags": [ { "name": "Events" }, { "name": "Registrations" }, { "name": "Me" }, { "name": "Check-in" }, { "name": "Accounts" } ], "paths": { "/events": { "get": { "tags": [ "Events" ], "summary": "Upcoming public events", "description": "Events anyone can see (active, not hidden, live) that have not ended, soonest first.\n\n**Who:** Anyone.", "operationId": "getEvents", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (at most 100)", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "q", "in": "query", "required": false, "description": "Search the title", "schema": { "type": "string", "maxLength": 100 } }, { "name": "campus", "in": "query", "required": false, "description": "A campus id or slug (its events plus church-wide ones), or 'all' for church-wide events only", "schema": { "type": "string", "maxLength": 64 } }, { "name": "series", "in": "query", "required": false, "description": "A series slug", "schema": { "type": "string", "maxLength": 120 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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))$" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "number", "description": "The headline price in rand (0 = free)" }, "pictureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiresRegistration": { "type": "boolean" }, "scheduleType": { "type": "string", "enum": [ "single", "sessions" ] }, "campus": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ], "description": "null = for all campuses (or campuses are off)" }, "series": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "title", "startDate", "endDate", "location", "price", "pictureUrl", "requiresRegistration", "scheduleType", "campus", "series" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Items across all pages" }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages (at least 1)" } }, "required": [ "page", "limit", "total", "pages" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events/{id}": { "get": { "tags": [ "Events" ], "summary": "One public event", "description": "With its ticket options (internal kids check-in and volunteer tickets left out) and sessions. Hidden events can be fetched by id (they are unlisted, not private).\n\n**Who:** Anyone.", "operationId": "getEventsId", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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))$" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "number", "description": "The headline price in rand (0 = free)" }, "pictureUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requiresRegistration": { "type": "boolean" }, "scheduleType": { "type": "string", "enum": [ "single", "sessions" ] }, "campus": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ], "description": "null = for all campuses (or campuses are off)" }, "series": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": false }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "registrationDeadline": { "anyOf": [ { "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))$" }, { "type": "null" } ] }, "ticketOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "price": { "type": "number", "description": "The normal price in rand" }, "currentPrice": { "type": "number", "description": "What it costs now (an early-bird price while one runs)" }, "isMainTicket": { "type": "boolean" }, "sessionMode": { "type": "string", "enum": [ "all", "pick" ], "description": "\"pick\" = the buyer chooses sessions" } }, "required": [ "id", "name", "price", "currentPrice", "isMainTicket", "sessionMode" ], "additionalProperties": false } }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "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))$" }, "endsAt": { "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))$" }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelled": { "type": "boolean" } }, "required": [ "id", "label", "startsAt", "endsAt", "location", "cancelled" ], "additionalProperties": false }, "description": "Multi-day events only; empty otherwise" } }, "required": [ "id", "title", "startDate", "endDate", "location", "price", "pictureUrl", "requiresRegistration", "scheduleType", "campus", "series", "description", "registrationDeadline", "ticketOptions", "sessions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registrations": { "post": { "tags": [ "Registrations" ], "summary": "Register for an event", "description": "Signed in, or as a guest for a free event that allows it (`guest` then required), or with a waitlist link (`waitlistToken`).\n\nRegistering again for the same event adds to the existing registration. When nothing is owed it is marked paid and tickets are issued; otherwise pay with `POST /registrations/{id}/checkout`.\n\nA coupon that was valid when checked but used up a moment later is reported in `couponError`; the registration is still made.\n\n**Who:** Anyone; signed-in staff may see more.", "operationId": "postRegistrations", "security": [ {}, { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 64 }, "options": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "eventOptionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "variantId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "sessionIds": { "description": "\"Pick sessions\" tickets: the sessions chosen", "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "required": [ "eventOptionId", "quantity" ] } }, "guest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "maxLength": 40 } }, "required": [ "name", "email" ] }, "couponCode": { "type": "string", "maxLength": 60 }, "attendees": { "description": "Names for the places (events that collect them)", "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "eventOptionId": { "type": "string", "minLength": 1, "maxLength": 64 }, "variantId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "dateOfBirth": { "description": "YYYY-MM-DD (youth events)", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "gender": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "parentName": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "parentEmail": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "parentPhone": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } }, "required": [ "eventOptionId", "name" ] } }, "ticketDelivery": { "description": "With attendees: tickets to the payer, or to each attendee", "type": "string", "enum": [ "payer", "each" ] }, "waitlistToken": { "type": "string", "maxLength": 200 }, "analyticsSessionId": { "type": "string", "maxLength": 100 } }, "required": [ "eventId", "options" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "partial_paid", "paid", "cancelled" ] }, "createdAt": { "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))$" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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": [ "id", "title", "startDate", "endDate" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "ticket": { "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPrice": { "type": "number" } }, "required": [ "ticket", "variant", "quantity", "unitPrice" ], "additionalProperties": false } }, "totalDue": { "type": "number", "description": "In rand, after discounts" }, "amountPaid": { "type": "number", "description": "In rand (refunds subtracted)" }, "balance": { "type": "number", "description": "totalDue − amountPaid; 0 or less = nothing owing" }, "isNew": { "type": "boolean", "description": "false = added to an existing registration" }, "couponError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "createdAt", "event", "items", "totalDue", "amountPaid", "balance", "isNew", "couponError" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registrations/{id}": { "get": { "tags": [ "Registrations" ], "summary": "One of my registrations", "description": "**Who:** Any signed-in person.", "operationId": "getRegistrationsId", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "partial_paid", "paid", "cancelled" ] }, "createdAt": { "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))$" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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": [ "id", "title", "startDate", "endDate" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "ticket": { "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPrice": { "type": "number" } }, "required": [ "ticket", "variant", "quantity", "unitPrice" ], "additionalProperties": false } }, "totalDue": { "type": "number", "description": "In rand, after discounts" }, "amountPaid": { "type": "number", "description": "In rand (refunds subtracted)" }, "balance": { "type": "number", "description": "totalDue − amountPaid; 0 or less = nothing owing" } }, "required": [ "id", "status", "createdAt", "event", "items", "totalDue", "amountPaid", "balance" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registrations/{id}/cancel": { "post": { "tags": [ "Registrations" ], "summary": "Cancel my registration", "description": "Not after the event has ended, and not once anything has been paid (the church can do that). Its places go to the waitlist.\n\n**Who:** Any signed-in person.", "operationId": "postRegistrationsIdCancel", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "partial_paid", "paid", "cancelled" ] }, "createdAt": { "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))$" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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": [ "id", "title", "startDate", "endDate" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "ticket": { "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPrice": { "type": "number" } }, "required": [ "ticket", "variant", "quantity", "unitPrice" ], "additionalProperties": false } }, "totalDue": { "type": "number", "description": "In rand, after discounts" }, "amountPaid": { "type": "number", "description": "In rand (refunds subtracted)" }, "balance": { "type": "number", "description": "totalDue − amountPaid; 0 or less = nothing owing" } }, "required": [ "id", "status", "createdAt", "event", "items", "totalDue", "amountPaid", "balance" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/registrations/{id}/checkout": { "post": { "tags": [ "Registrations" ], "summary": "Pay what I owe online", "description": "Starts a payment with the church's provider (Yoco or PayFast) and returns where to send the person (`redirectUrl`).\n\nIf an early-bird price ran out since the registration was made, nothing is started: `priceUpdated` is true with the new amount owing — show it, then call again.\n\n**Who:** Any signed-in person.", "operationId": "postRegistrationsIdCheckout", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "donationAmount": { "description": "An optional donation added on top, in rand", "type": "number", "minimum": 0, "maximum": 100000 }, "provider": { "description": "yoco or payfast (default: the first one switched on)", "type": "string", "maxLength": 40 }, "successUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "cancelUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "failureUrl": { "type": "string", "maxLength": 2000, "format": "uri" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "priceUpdated": { "type": "boolean", "const": true }, "newBalance": { "type": "number" }, "message": { "type": "string" } }, "required": [ "priceUpdated", "newBalance", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "priceUpdated": { "type": "boolean", "const": false }, "checkoutId": { "type": "string" }, "redirectUrl": { "type": "string" }, "provider": { "type": "string" }, "amount": { "type": "number", "description": "Charged now, in rand (with any donation)" } }, "required": [ "priceUpdated", "checkoutId", "redirectUrl", "provider", "amount" ], "additionalProperties": false } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "tags": [ "Me" ], "summary": "The signed-in person", "description": "**Who:** Any signed-in person.", "operationId": "getMe", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "admin", "supervisor", "staff", "user" ] }, "twoFactorEnabled": { "type": "boolean" }, "notificationPreference": { "type": "string", "enum": [ "email", "whatsapp", "both" ] }, "homeCampusId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "createdAt": { "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": [ "id", "name", "email", "phone", "role", "twoFactorEnabled", "notificationPreference", "homeCampusId", "createdAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Me" ], "summary": "Change my details", "description": "Only what is sent changes. A new `password` needs `currentPassword`; it sends a security notice and stops other devices skipping the 2FA code. The answer has a fresh `token` (the old one keeps working).\n\n**Who:** Any signed-in person.", "operationId": "patchMe", "security": [ { "bearerAuth": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "description": "null or empty removes it", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "notificationPreference": { "type": "string", "enum": [ "email", "whatsapp", "both" ] }, "homeCampusId": { "description": "While campuses are on", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "password": { "type": "string", "minLength": 8, "maxLength": 200 }, "currentPassword": { "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "role": { "type": "string", "enum": [ "admin", "supervisor", "staff", "user" ] }, "twoFactorEnabled": { "type": "boolean" }, "notificationPreference": { "type": "string", "enum": [ "email", "whatsapp", "both" ] }, "homeCampusId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "createdAt": { "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": [ "id", "name", "email", "phone", "role", "twoFactorEnabled", "notificationPreference", "homeCampusId", "createdAt" ], "additionalProperties": false }, "token": { "type": "string" } }, "required": [ "data", "token" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me/registrations": { "get": { "tags": [ "Me" ], "summary": "My registrations", "description": "Newest first. By default only ones for events that have not ended, and not cancelled; `past=true` lists everything.\n\n**Who:** Any signed-in person.", "operationId": "getMeRegistrations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (at most 100)", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "past", "in": "query", "required": false, "description": "Include past and cancelled registrations", "schema": { "default": "false", "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "status": { "type": "string", "enum": [ "pending", "confirmed", "partial_paid", "paid", "cancelled" ] }, "createdAt": { "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))$" }, "event": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "title": { "type": "string" }, "startDate": { "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))$" }, "endDate": { "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": [ "id", "title", "startDate", "endDate" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "ticket": { "type": "string" }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unitPrice": { "type": "number" } }, "required": [ "ticket", "variant", "quantity", "unitPrice" ], "additionalProperties": false } }, "totalDue": { "type": "number", "description": "In rand, after discounts" }, "amountPaid": { "type": "number", "description": "In rand (refunds subtracted)" }, "balance": { "type": "number", "description": "totalDue − amountPaid; 0 or less = nothing owing" } }, "required": [ "id", "status", "createdAt", "event", "items", "totalDue", "amountPaid", "balance" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Items across all pages" }, "pages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Number of pages (at least 1)" } }, "required": [ "page", "limit", "total", "pages" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkin/{qrCode}": { "get": { "tags": [ "Check-in" ], "summary": "Look a ticket up before checking it in", "description": "Who it is for, how many are left to check in (for today's session on multi-day events, or `sessionId`), and parental consent. Nothing is changed.\n\n**Who:** Staff, supervisors and admins.", "operationId": "getCheckinQrCode", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "qrCode", "in": "path", "required": true, "description": "The code in the ticket's QR", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "sessionId", "in": "query", "required": false, "description": "Multi-day events: the session (default: today's)", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "found", "transferred" ] }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "For a transferred ticket: who has it now" }, "ticket": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 64 }, "eventTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ticketName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variant": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "holder": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The attendee named on it, or the person who registered" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Still to check in (this session, on multi-day events)" }, "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, { "type": "null" } ] }, "sessionError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why no session is open for check-in now" }, "consentStatus": { "type": "string", "description": "not_required, given, pending, declined or missing" } }, "required": [ "id", "eventId", "eventTitle", "ticketName", "variant", "holder", "quantity", "remaining", "session", "sessionError", "consentStatus" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "outcome", "message", "ticket" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed for this role (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Check-in" ], "summary": "Check a ticket in", "description": "Checks in everyone left on the ticket, or `people`. Every normal result is a 200 with an `outcome`:\n\n`checked_in`, `already_used`, `consent_required` (a supervisor can resend with `overrideConsent`, which is logged), `wrong_event`, `wrong_section`, `section_not_found`, `no_session` (multi-day: nothing open now), `locked` (offline-locked to another device) or `transferred` (handed on; `message` says to whom).\n\nAn unknown code is `NOT_FOUND`.\n\n**Who:** Staff, supervisors and admins.", "operationId": "postCheckinQrCode", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "qrCode", "in": "path", "required": true, "description": "The code in the ticket's QR", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "description": "Refuse tickets for any other event", "type": "string", "minLength": 1, "maxLength": 64 }, "sectionId": { "description": "Only tickets valid for this section", "type": "string", "minLength": 1, "maxLength": 64 }, "sessionId": { "description": "Multi-day events: the session (default: today's)", "type": "string", "minLength": 1, "maxLength": 64 }, "people": { "description": "How many to check in (default: everyone left)", "type": "integer", "minimum": 1, "maximum": 10000 }, "overrideConsent": { "type": "boolean" }, "deviceId": { "description": "This scanner, so its own offline lock doesn't block it", "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "checked_in", "already_used", "consent_required", "wrong_event", "wrong_section", "section_not_found", "no_session", "locked", "transferred" ] }, "message": { "type": "string" }, "ticket": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 64 }, "eventTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ticketName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ticket option, e.g. \"Adult\"" }, "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People on this ticket" } }, "required": [ "id", "eventId", "eventTitle", "ticketName", "quantity" ], "additionalProperties": false }, { "type": "null" } ] }, "checkedIn": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "People checked in by this request (0 unless checked_in)" }, "remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Still to check in afterwards" }, "session": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "label": { "type": "string" } }, "required": [ "id", "label" ], "additionalProperties": false }, { "type": "null" } ] }, "consentStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canOverride": { "type": "boolean", "description": "consent_required: whether you may override" } }, "required": [ "outcome", "message", "ticket", "checkedIn", "remaining", "session", "consentStatus", "canOverride" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in (UNAUTHENTICATED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not allowed for this role (FORBIDDEN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found (NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/signup": { "post": { "tags": [ "Accounts" ], "summary": "Create an account", "description": "Signs the new account in straight away. `acceptTerms` must be true (the Terms of Use and Privacy Policy); `newsOptIn` is the unticked \"News & announcements\" box.\n\n**Who:** Anyone.", "operationId": "postAuthSignup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "password": { "type": "string", "minLength": 8, "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "notificationPreference": { "description": "WhatsApp needs a valid South African number; otherwise email is used", "type": "string", "enum": [ "email", "whatsapp", "both" ] }, "newsOptIn": { "type": "boolean" }, "acceptTerms": { "type": "boolean", "const": true } }, "required": [ "name", "email", "password", "acceptTerms" ] } } } }, "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "signed_in" }, "token": { "type": "string", "description": "Send as `Authorization: Bearer `" }, "user": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "supervisor", "staff", "user" ] } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false }, "newsPromptPending": { "type": "boolean", "description": "Ask once whether they want News & announcements" }, "noticePromptPending": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "string", "enum": [ "first", "updated" ] } ], "description": "A privacy notice they must accept: never accepted (first) or a newer version (updated)" }, "deviceToken": { "description": "With rememberDevice: send it with the next login to skip the code on this device", "type": "string" } }, "required": [ "status", "token", "user", "newsPromptPending", "noticePromptPending" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/login": { "post": { "tags": [ "Accounts" ], "summary": "Log in", "description": "With an email address or phone number. Five wrong passwords lock the account for five minutes (`RATE_LIMITED`).\n\nWith two-factor authentication (always for supervisors and admins), the answer is `code_required`: a code was sent by email or WhatsApp — finish with `POST /auth/login/code`.\n\n**Who:** Anyone.", "operationId": "postAuthLogin", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identifier": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Email address or phone number" }, "password": { "type": "string", "minLength": 1, "maxLength": 200 }, "deviceToken": { "description": "From an earlier login with rememberDevice", "type": "string", "maxLength": 500 } }, "required": [ "identifier", "password" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "signed_in" }, "token": { "type": "string", "description": "Send as `Authorization: Bearer `" }, "user": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "supervisor", "staff", "user" ] } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false }, "newsPromptPending": { "type": "boolean", "description": "Ask once whether they want News & announcements" }, "noticePromptPending": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "string", "enum": [ "first", "updated" ] } ], "description": "A privacy notice they must accept: never accepted (first) or a newer version (updated)" }, "deviceToken": { "description": "With rememberDevice: send it with the next login to skip the code on this device", "type": "string" } }, "required": [ "status", "token", "user", "newsPromptPending", "noticePromptPending" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "code_required" }, "challengeId": { "type": "string" }, "method": { "type": "string", "enum": [ "email", "whatsapp" ] }, "destination": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Where the code went, partly hidden" }, "enrolling": { "type": "boolean", "description": "true = this turns two-factor on (required for the role)" } }, "required": [ "status", "challengeId", "method", "destination", "enrolling" ], "additionalProperties": false } ] } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/login/code": { "post": { "tags": [ "Accounts" ], "summary": "Finish logging in with the code", "description": "**Who:** Anyone.", "operationId": "postAuthLoginCode", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "code": { "type": "string", "minLength": 4, "maxLength": 12 }, "rememberDevice": { "description": "Skip the code on this device next time (30 days)", "type": "boolean" } }, "required": [ "challengeId", "code" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "signed_in" }, "token": { "type": "string", "description": "Send as `Authorization: Bearer `" }, "user": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "supervisor", "staff", "user" ] } }, "required": [ "id", "name", "email", "role" ], "additionalProperties": false }, "newsPromptPending": { "type": "boolean", "description": "Ask once whether they want News & announcements" }, "noticePromptPending": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "string", "enum": [ "first", "updated" ] } ], "description": "A privacy notice they must accept: never accepted (first) or a newer version (updated)" }, "deviceToken": { "description": "With rememberDevice: send it with the next login to skip the code on this device", "type": "string" } }, "required": [ "status", "token", "user", "newsPromptPending", "noticePromptPending" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Validation failed (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "VALIDATION_FAILED", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "RATE_LIMITED", "READ_ONLY", "INTERNAL" ] }, "message": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Per-field problems (VALIDATION_FAILED only)" } } } } } } } }