{ "openapi": "3.0.3", "info": { "title": "sondahub Identity API", "version": "0.6.1", "description": "A company directory: people, groups and memberships — behind SCIM 2.0, SAML and OpenID Connect.\n\nThree hundred people at a made-up company, Orbit Labs, in forty groups — departments, teams, roles, offices — with managers, titles and employee numbers. The same directory answers SCIM 2.0 at /scim/v2, signs people in over SAML at /saml/sso and fills OpenID Connect userinfo, so the person SCIM lists is the person who logs in.\n\nNo keys, no accounts. Writes (POST, PUT, PATCH, DELETE) are validated and answered exactly as a real server would answer them, then forgotten: sondahub stores nothing, and every such answer says so in _note and in the X-Sondahub-Write: simulated header. Every list takes page, limit, sort, q, fields and expand, plus one filter per field with the operators _ne _gt _gte _lt _lte _like _in.", "contact": { "name": "sondahub", "url": "https://api.sondahub.com" } }, "servers": [ { "url": "https://api.sondahub.com" } ], "tags": [ { "name": "users", "description": "People. user_name is unique and is the login everywhere (SAML, OIDC password grant: password \"probe\"); email is user_name@orbit.example." }, { "name": "groups", "description": "Departments, teams, roles and offices. member_count follows the memberships." }, { "name": "memberships", "description": "A person in a group. POST one to add someone (409 if they are in it already); DELETE it to take them out." } ], "paths": { "/v1/identity/users": { "get": { "tags": [ "users" ], "summary": "List users", "operationId": "list_users", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: manager, reports, memberships.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "user_name", "in": "query", "required": false, "description": "Filter: user_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "description": "Unique login.", "example": "ada.lovelace" } }, { "name": "given_name", "in": "query", "required": false, "description": "Filter: given_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "Ada" } }, { "name": "family_name", "in": "query", "required": false, "description": "Filter: family_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "Lovelace" } }, { "name": "display_name", "in": "query", "required": false, "description": "Filter: display_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "description": "Defaults to given and family name." } }, { "name": "email", "in": "query", "required": false, "description": "Filter: email equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "ada.lovelace@orbit.example" } }, { "name": "title", "in": "query", "required": false, "description": "Filter: title equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "Staff Engineer" } }, { "name": "department", "in": "query", "required": false, "description": "Filter: department equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "Engineering" } }, { "name": "employee_number", "in": "query", "required": false, "description": "Filter: employee_number equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "E1042" } }, { "name": "manager_id", "in": "query", "required": false, "description": "Filter: manager_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Who this person reports to; null for the CEO. The id of a user." } }, { "name": "phone", "in": "query", "required": false, "description": "Filter: phone equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "locale", "in": "query", "required": false, "description": "Filter: locale equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "en-US" } }, { "name": "timezone", "in": "query", "required": false, "description": "Filter: timezone equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "America/New_York" } }, { "name": "office", "in": "query", "required": false, "description": "Filter: office equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "New York" } }, { "name": "active", "in": "query", "required": false, "description": "Filter: active equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "boolean", "nullable": true, "description": "false: deprovisioned — cannot sign in." } }, { "name": "external_id", "in": "query", "required": false, "description": "Filter: external_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "description": "The id an upstream system (an HR tool, an IdP) knows this person by." } }, { "name": "last_login_at", "in": "query", "required": false, "description": "Filter: last_login_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "users" ], "summary": "Create a user", "operationId": "create_user", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/users/{id}": { "get": { "tags": [ "users" ], "summary": "Get a user", "operationId": "get_user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "users" ], "summary": "Replace a user", "operationId": "replace_user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "users" ], "summary": "Update part of a user", "operationId": "update_user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "users" ], "summary": "Delete a user", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/users/{id}/manager": { "get": { "tags": [ "users" ], "summary": "The manager of a user", "operationId": "user_manager", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/users/{id}/reports": { "get": { "tags": [ "users" ], "summary": "The reports of a user", "operationId": "user_reports", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/users/{id}/memberships": { "get": { "tags": [ "users" ], "summary": "The memberships of a user", "operationId": "user_memberships", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/groups": { "get": { "tags": [ "groups" ], "summary": "List groups", "operationId": "list_groups", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: memberships.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "display_name", "in": "query", "required": false, "description": "Filter: display_name equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "example": "Platform Team" } }, { "name": "slug", "in": "query", "required": false, "description": "Filter: slug equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true, "example": "platform-team" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter: kind equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "department", "team", "role", "office", "list" ], "nullable": true, "example": "team" } }, { "name": "external_id", "in": "query", "required": false, "description": "Filter: external_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "nullable": true } }, { "name": "member_count", "in": "query", "required": false, "description": "Filter: member_count equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "readOnly": true } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "groups" ], "summary": "Create a group", "operationId": "create_group", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/groups/{id}": { "get": { "tags": [ "groups" ], "summary": "Get a group", "operationId": "get_group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "groups" ], "summary": "Replace a group", "operationId": "replace_group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "groups" ], "summary": "Update part of a group", "operationId": "update_group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "groups" ], "summary": "Delete a group", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/groups/{id}/memberships": { "get": { "tags": [ "groups" ], "summary": "The memberships of a group", "operationId": "group_memberships", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of related records.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipList" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/memberships": { "get": { "tags": [ "memberships" ], "summary": "List memberships", "operationId": "list_memberships", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }, { "name": "sort", "in": "query", "description": "Comma-separated fields; prefix with - for descending. Default: id.", "schema": { "type": "string", "example": "-id" } }, { "name": "q", "in": "query", "description": "Full-text search over the string fields.", "schema": { "type": "string" } }, { "name": "fields", "in": "query", "description": "Comma-separated fields to return.", "schema": { "type": "string" } }, { "name": "expand", "in": "query", "description": "Comma-separated relations to embed: user, group.", "schema": { "type": "string" } }, { "name": "id", "in": "query", "required": false, "description": "Filter: id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter: created_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true } }, { "name": "updated_at", "in": "query", "required": false, "description": "Filter: updated_at equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true } }, { "name": "user_id", "in": "query", "required": false, "description": "Filter: user_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "description": "The id of a user." } }, { "name": "group_id", "in": "query", "required": false, "description": "Filter: group_id equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "integer", "description": "The id of a group." } }, { "name": "role", "in": "query", "required": false, "description": "Filter: role equals the value. Suffix the name with _ne, _gt, _gte, _lt, _lte, _like (contains, case-insensitive) or _in (comma list); \"null\" matches missing values.", "schema": { "type": "string", "enum": [ "member", "owner" ], "nullable": true, "example": "member" } } ], "responses": { "200": { "description": "A page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipList" } } } }, "400": { "description": "A parameter could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "memberships" ], "summary": "Create a membership", "operationId": "create_membership", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipInput" } } } }, "responses": { "201": { "description": "Created — simulated: the answer is what a real server would give, nothing is stored (see _note and the X-Sondahub-Write header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/memberships/{id}": { "get": { "tags": [ "memberships" ], "summary": "Get a membership", "operationId": "get_membership", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 }, { "name": "expand", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } } }, "304": { "description": "Unchanged since the ETag you sent." }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "memberships" ], "summary": "Replace a membership", "operationId": "replace_membership", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "memberships" ], "summary": "Update part of a membership", "operationId": "update_membership", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipInput" } } } }, "responses": { "200": { "description": "The record as it would have been saved — simulated, nothing is stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The body failed validation; details lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "memberships" ], "summary": "Delete a membership", "description": "Simulated: answers 200 with the record that would have been removed and a note; nothing is stored.", "operationId": "delete_membership", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "What would have been deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "integer" }, "_note": { "type": "string" } } } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/memberships/{id}/user": { "get": { "tags": [ "memberships" ], "summary": "The user of a membership", "operationId": "membership_user", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/identity/memberships/{id}/group": { "get": { "tags": [ "memberships" ], "summary": "The group of a membership", "operationId": "membership_group", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "example": 1 } ], "responses": { "200": { "description": "The related record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "404": { "description": "No such record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "validation_failed" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "code", "message" ] } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "pages": { "type": "integer" } } }, "User": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "user_name": { "type": "string", "description": "Unique login.", "example": "ada.lovelace" }, "given_name": { "type": "string", "example": "Ada" }, "family_name": { "type": "string", "example": "Lovelace" }, "display_name": { "type": "string", "nullable": true, "description": "Defaults to given and family name." }, "email": { "type": "string", "example": "ada.lovelace@orbit.example" }, "title": { "type": "string", "nullable": true, "example": "Staff Engineer" }, "department": { "type": "string", "nullable": true, "example": "Engineering" }, "employee_number": { "type": "string", "nullable": true, "example": "E1042" }, "manager_id": { "type": "integer", "nullable": true, "description": "Who this person reports to; null for the CEO. The id of a user." }, "phone": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true, "example": "en-US" }, "timezone": { "type": "string", "nullable": true, "example": "America/New_York" }, "office": { "type": "string", "nullable": true, "example": "New York" }, "active": { "type": "boolean", "nullable": true, "description": "false: deprovisioned — cannot sign in." }, "external_id": { "type": "string", "nullable": true, "description": "The id an upstream system (an HR tool, an IdP) knows this person by." }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "created_at", "updated_at", "user_name", "given_name", "family_name", "email" ] }, "UserInput": { "type": "object", "properties": { "user_name": { "type": "string", "description": "Unique login.", "example": "ada.lovelace" }, "given_name": { "type": "string", "example": "Ada" }, "family_name": { "type": "string", "example": "Lovelace" }, "display_name": { "type": "string", "nullable": true, "description": "Defaults to given and family name." }, "email": { "type": "string", "example": "ada.lovelace@orbit.example" }, "title": { "type": "string", "nullable": true, "example": "Staff Engineer" }, "department": { "type": "string", "nullable": true, "example": "Engineering" }, "employee_number": { "type": "string", "nullable": true, "example": "E1042" }, "manager_id": { "type": "integer", "nullable": true, "description": "Who this person reports to; null for the CEO. The id of a user." }, "phone": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true, "example": "en-US" }, "timezone": { "type": "string", "nullable": true, "example": "America/New_York" }, "office": { "type": "string", "nullable": true, "example": "New York" }, "active": { "type": "boolean", "nullable": true, "description": "false: deprovisioned — cannot sign in." }, "external_id": { "type": "string", "nullable": true, "description": "The id an upstream system (an HR tool, an IdP) knows this person by." }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "user_name", "given_name", "family_name", "email" ], "example": { "user_name": "ada.lovelace", "given_name": "Ada", "family_name": "Lovelace", "email": "ada.lovelace@orbit.example", "title": "Staff Engineer", "department": "Engineering", "employee_number": "E1042", "locale": "en-US", "timezone": "America/New_York", "office": "New York" } }, "UserList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Group": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "display_name": { "type": "string", "example": "Platform Team" }, "slug": { "type": "string", "nullable": true, "example": "platform-team" }, "kind": { "type": "string", "enum": [ "department", "team", "role", "office", "list" ], "nullable": true, "example": "team" }, "description": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true }, "member_count": { "type": "integer", "nullable": true, "readOnly": true } }, "required": [ "id", "created_at", "updated_at", "display_name", "member_count" ] }, "GroupInput": { "type": "object", "properties": { "display_name": { "type": "string", "example": "Platform Team" }, "slug": { "type": "string", "nullable": true, "example": "platform-team" }, "kind": { "type": "string", "enum": [ "department", "team", "role", "office", "list" ], "nullable": true, "example": "team" }, "description": { "type": "string", "nullable": true }, "external_id": { "type": "string", "nullable": true } }, "required": [ "display_name" ], "example": { "display_name": "Platform Team", "slug": "platform-team", "kind": "team" } }, "GroupList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "Membership": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true, "description": "Assigned by the server. Seed records keep their ids across restarts; records you create continue after the seed.", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record was created (ISO 8601, UTC).", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the record last changed.", "readOnly": true }, "user_id": { "type": "integer", "description": "The id of a user." }, "group_id": { "type": "integer", "description": "The id of a group." }, "role": { "type": "string", "enum": [ "member", "owner" ], "nullable": true, "example": "member" } }, "required": [ "id", "created_at", "updated_at", "user_id", "group_id" ] }, "MembershipInput": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "The id of a user." }, "group_id": { "type": "integer", "description": "The id of a group." }, "role": { "type": "string", "enum": [ "member", "owner" ], "nullable": true, "example": "member" } }, "required": [ "user_id", "group_id" ], "example": { "user_id": 1, "group_id": 1, "role": "member" } }, "MembershipList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } } } } }