{ "openapi": "3.1.0", "info": { "title": "Laravel", "version": "0.0.1", "description": "Tap API. There are three separate login areas: `staff`, `anchor` and `contractor`.\n\nTo try authenticated endpoints: call `POST \/{portal}\/auth\/login`, copy the `token`\nfrom the response, click **Authorize** and paste it in. Logging in again\n(anywhere) revokes the previous token." }, "servers": [ { "url": "http:\/\/tap-backend.bizwizrp.com\/api" } ], "tags": [ { "name": "Auth" }, { "name": "Profile" }, { "name": "Staff \u00b7 Users" }, { "name": "Staff \u00b7 Anchors" }, { "name": "Staff \u00b7 Anchor users" }, { "name": "Staff \u00b7 Contractors" }, { "name": "Staff \u00b7 Contractor users" } ], "security": [ { "http": [] } ], "paths": { "\/portal": { "get": { "operationId": "portal.show", "description": "The web app calls this on start-up to learn whether it is the staff,\nanchor or contractor site. The answer comes from the browser's Origin\nheader matched against the portal URLs in the backend's .env. Calls\nfrom any other site (including these docs) are refused and logged.", "summary": "Which portal the calling site is", "tags": [ "Auth" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "portal": { "type": "string", "enum": [ "staff", "anchor", "contractor" ] } }, "required": [ "portal" ] } } } } }, "security": [] } }, "\/{portal}\/auth\/login": { "post": { "operationId": "auth.login", "description": "Logging in revokes any previous token, so the account is only ever\nsigned in on one device. From a browser, the portal must match the\nsite the request comes from, otherwise it is refused and logged.", "summary": "Log in with an email address or phone number and a password", "tags": [ "Auth" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "$ref": "#\/components\/schemas\/Portal" }, "example": "staff" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "description": "Email address or phone number." }, "password": { "type": "string" } }, "required": [ "login", "password" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_at": { "type": [ "string", "null" ] }, "user": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "token", "token_type", "expires_at", "user" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } }, "security": [] } }, "\/{portal}\/auth\/me": { "get": { "operationId": "auth.me", "summary": "The currently logged in account", "tags": [ "Auth" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "$ref": "#\/components\/schemas\/Portal" }, "example": "staff" } ], "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/{portal}\/auth\/logout": { "post": { "operationId": "auth.logout", "summary": "Log out, revoking the current token", "tags": [ "Auth" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "type": "string" }, "example": "staff" } ], "responses": { "204": { "description": "No content" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/{portal}\/profile\/email": { "put": { "operationId": "profile.email", "summary": "Change my email address", "tags": [ "Profile" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "$ref": "#\/components\/schemas\/Portal" }, "example": "staff" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "current_password": { "type": "string" } }, "required": [ "email", "current_password" ] } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/{portal}\/profile\/phone": { "put": { "operationId": "profile.phone", "summary": "Change my phone number", "tags": [ "Profile" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "$ref": "#\/components\/schemas\/Portal" }, "example": "staff" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Any format: 0712345678, +254 712 345 678 or 254712345678. Stored as 254712345678.", "pattern": "^\\d{10,15}$" }, "current_password": { "type": "string" } }, "required": [ "phone", "current_password" ] } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/{portal}\/profile\/password": { "put": { "operationId": "profile.password", "description": "The session making the change stays signed in. Any other token for the\naccount is revoked.", "summary": "Change my password", "tags": [ "Profile" ], "parameters": [ { "name": "portal", "in": "path", "required": true, "description": "Which login area: staff, anchor or contractor.", "schema": { "type": "string" }, "example": "staff" } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "current_password": { "type": "string" }, "password": { "type": "string", "description": "At least 8 characters, with at least one letter and one number." }, "password_confirmation": { "type": "string" } }, "required": [ "current_password", "password", "password_confirmation" ] } } } }, "responses": { "204": { "description": "No content" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/users": { "get": { "operationId": "users.index", "summary": "List staff users", "tags": [ "Staff \u00b7 Users" ], "responses": { "200": { "description": "Paginated set of `AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AccountResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "users.store", "summary": "Create a staff user", "tags": [ "Staff \u00b7 Users" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "name", "email", "phone", "password" ] } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/users\/{user}": { "get": { "operationId": "users.show", "summary": "Get a staff user", "tags": [ "Staff \u00b7 Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "users.update", "summary": "Update a staff user. Changing the password or deactivating logs them out", "tags": [ "Staff \u00b7 Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "users.destroy", "summary": "Delete (soft) a staff user and log them out. You cannot delete yourself", "tags": [ "Staff \u00b7 Users" ], "parameters": [ { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "You cannot delete your own account." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/anchors": { "get": { "operationId": "anchors.index", "summary": "List anchors", "tags": [ "Staff \u00b7 Anchors" ], "responses": { "200": { "description": "Paginated set of `OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "anchors.store", "summary": "Create an anchor", "tags": [ "Staff \u00b7 Anchors" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/anchors\/{anchor}": { "get": { "operationId": "anchors.show", "summary": "Get an anchor", "tags": [ "Staff \u00b7 Anchors" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "anchors.update", "summary": "Update an anchor", "tags": [ "Staff \u00b7 Anchors" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "anchors.destroy", "summary": "Delete an anchor. Only allowed once it has no users (including deleted ones)", "tags": [ "Staff \u00b7 Anchors" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "This anchor still has users." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/anchors\/{anchor}\/users": { "get": { "operationId": "anchors.users.index", "summary": "List an anchor's users", "tags": [ "Staff \u00b7 Anchor users" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated set of `AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AccountResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "anchors.users.store", "summary": "Create a user for an anchor", "tags": [ "Staff \u00b7 Anchor users" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "name", "email", "phone", "password" ] } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/anchors\/{anchor}\/users\/{user}": { "get": { "operationId": "anchors.users.show", "summary": "Get one of an anchor's users", "tags": [ "Staff \u00b7 Anchor users" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "anchors.users.update", "summary": "Update an anchor user. Changing the password or deactivating logs them out", "tags": [ "Staff \u00b7 Anchor users" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "anchors.users.destroy", "summary": "Delete (soft) an anchor user and log them out", "tags": [ "Staff \u00b7 Anchor users" ], "parameters": [ { "name": "anchor", "in": "path", "required": true, "description": "The anchor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/contractors": { "get": { "operationId": "contractors.index", "summary": "List contractors", "tags": [ "Staff \u00b7 Contractors" ], "responses": { "200": { "description": "Paginated set of `OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "contractors.store", "summary": "Create a contractor", "tags": [ "Staff \u00b7 Contractors" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/contractors\/{contractor}": { "get": { "operationId": "contractors.show", "summary": "Get a contractor", "tags": [ "Staff \u00b7 Contractors" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "contractors.update", "summary": "Update a contractor", "tags": [ "Staff \u00b7 Contractors" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "`OrganizationResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/OrganizationResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "contractors.destroy", "summary": "Delete a contractor. Only allowed once it has no users (including deleted ones)", "tags": [ "Staff \u00b7 Contractors" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "This contractor still has users." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/contractors\/{contractor}\/users": { "get": { "operationId": "contractors.users.index", "summary": "List a contractor's users", "tags": [ "Staff \u00b7 Contractor users" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Paginated set of `AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AccountResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "contractors.users.store", "summary": "Create a user for a contractor", "tags": [ "Staff \u00b7 Contractor users" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "name", "email", "phone", "password" ] } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/staff\/contractors\/{contractor}\/users\/{user}": { "get": { "operationId": "contractors.users.show", "summary": "Get one of a contractor's users", "tags": [ "Staff \u00b7 Contractor users" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "put": { "operationId": "contractors.users.update", "summary": "Update a contractor user. Changing the password or deactivating logs them out", "tags": [ "Staff \u00b7 Contractor users" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Stored in international format, e.g. 0712345678 becomes 254712345678.", "pattern": "^\\d{10,15}$" }, "password": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "`AccountResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/AccountResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "delete": { "operationId": "contractors.users.destroy", "summary": "Delete (soft) a contractor user and log them out", "tags": [ "Staff \u00b7 Contractor users" ], "parameters": [ { "name": "contractor", "in": "path", "required": true, "description": "The contractor ID", "schema": { "type": "integer" } }, { "name": "user", "in": "path", "required": true, "description": "The user ID", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "AccountResource": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "is_active": { "type": "string" }, "anchor": { "$ref": "#\/components\/schemas\/OrganizationResource" }, "contractor": { "$ref": "#\/components\/schemas\/OrganizationResource" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "name", "email", "phone", "is_active", "created_at", "updated_at" ], "title": "AccountResource" }, "OrganizationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "created_at", "updated_at" ], "title": "OrganizationResource" }, "Portal": { "type": "string", "description": "The three separate login areas of the API, each backed by its own table.\n", "enum": [ "staff", "anchor", "contractor" ], "title": "Portal" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }