{ "openapi": "3.0.0", "info": { "title": "EUMA", "description": "External User Management API", "version": "1.0.0" }, "paths": { "/api/group/{groupId}": { "get": { "tags": [ "User groups" ], "summary": "Retrieves details of a user group.", "operationId": "get_group-details", "parameters": [ { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User group details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group not found" } } }, "delete": { "tags": [ "User groups" ], "summary": "Deletes a user group.", "operationId": "delete_group-delete", "parameters": [ { "name": "groupId", "in": "path", "description": "User group identifier", "required": true, "schema": { "type": "string" }, "example": "user-group-1" } ], "responses": { "200": { "description": "Group removed" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group not found" } } }, "patch": { "tags": [ "User groups" ], "summary": "Updates the user group name.", "operationId": "patch_group-update", "parameters": [ { "name": "groupId", "in": "path", "description": "User group identifier", "required": true, "schema": { "type": "string" }, "example": "user-group-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGroupRequest" } } } }, "responses": { "200": { "description": "User group after modification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "400": { "description": "Failed to modify user group. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group not found" }, "422": { "description": "Failed to modify user group. See response for details" } } } }, "/api/groups": { "get": { "tags": [ "User groups" ], "summary": "Retrieves a list of all current user groups.", "operationId": "get_groups-list", "responses": { "200": { "description": "Lists existing user groups", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/GroupResponse" } } } } }, "401": { "description": "Invalid or inactive API key" } } }, "post": { "tags": [ "User groups" ], "summary": "Creates a new user group.", "operationId": "post_group-create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGroupRequest" } } } }, "responses": { "200": { "description": "Newly created user group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupResponse" } } } }, "400": { "description": "Failed to create user group. See response for details." }, "401": { "description": "Invalid or inactive API key" } } } }, "/api/invitation/{userId}/roles": { "patch": { "tags": [ "Invitations" ], "summary": "Updates the invited user\u2019s roles.", "description": "Replaces the assigned roles. Include every role you want to keep.\n\nFor Manager, include at least one existing organisation unit in `managedOrganisationUnits`.\nFor learner without Manager, send `managedOrganisationUnits: []`.\nTo keep both roles, send `roles: [learner, manager]`.\n\nUse this endpoint for invited users.", "operationId": "patch_update_invited_user_roles", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRolesRequest" }, "examples": { "learner": { "summary": "Learner only", "description": "Replaces all current roles with learner. Any other role is removed.", "value": { "roles": [ "learner" ], "managedOrganisationUnits": [] } }, "manager": { "summary": "Manager only", "description": "Replaces all current roles with manager. Replace the organisation-unit ID with an existing one. Include learner in roles too if that role should be retained.", "value": { "roles": [ "manager" ], "managedOrganisationUnits": [ "existing-organisation-unit-id" ] } } } } } }, "responses": { "200": { "description": "Invited user roles updated" }, "400": { "description": "Validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } } }, "/api/invitation/{userId}/organisation-unit": { "delete": { "tags": [ "Invitations" ], "summary": "Removes the invited user from the organisation unit to which they are assigned.", "operationId": "delete_clear_invited_user_ou", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string", "example": "example@example.com" } } ], "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } }, "patch": { "tags": [ "Invitations" ], "summary": "Updates the invited user's organisation unit assignment.", "operationId": "patch_move_invited_user_to_ou", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string", "example": "example@example.com" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignOrganisationUnitRequest" } } } }, "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "400": { "description": "Validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User or target organisation unit does not exist or is unavailable" } } } }, "/api/invitation/{userId}/groups": { "patch": { "tags": [ "Invitations" ], "summary": "Assigns an invited user to one or more groups.", "description": "Replaces the groups assigned to the invitation. Include every group you want to keep.\n\nProvide at least one group ID. Each ID must be a non-empty string that identifies an existing group.\n\nTo remove one group, use `DELETE /api/invitation/{userId}/group/{groupId}`.", "operationId": "patch_add-invited-group-member", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvitedUserGroupsRequest" } } } }, "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "type": "string", "example": "" } } } }, "default": { "description": "" } } } }, "/api/invitation/{userId}/group/{groupId}": { "delete": { "tags": [ "Invitations" ], "summary": "Removes an invited user from the group.", "operationId": "delete_remove-invited-group-member", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "User group identifier", "required": true, "schema": { "type": "string" }, "example": "user-group-1" } ], "responses": { "200": { "description": "User details after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group or user not found" }, "422": { "description": "User is not active" } } } }, "/api/invitation/{userId}/data": { "patch": { "tags": [ "Invitations" ], "summary": "Updates user invitation data.", "operationId": "patch_update_invitation_user_data", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvitationUserDataRequest" } } } }, "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "default": { "description": "" } } } }, "/api/invitation/{userId}/custom-fields": { "patch": { "tags": [ "Invitations" ], "summary": "Updates user invitation custom fields.", "operationId": "patch_update_invitation_custom-fields", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvitationCustomFieldsRequest" } } } }, "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "default": { "description": "" } } } }, "/api/invitation/{userId}/email-address": { "put": { "tags": [ "Invitations" ], "summary": "Updates the email address of the requested user. After the update, the user will be identified by the new email address.", "description": "Updates the email address of an invited or active user via the invitation URL. For `invited` users the existing invitation is updated to the new email and the invitation email is automatically re-sent to that address \u2014 no separate resend request is required. Equivalent to `PUT /api/user/{userId}` (Users); both routes share the same request and response shape.", "operationId": "put_invitation_update_email_address", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailAddressJsonRequest" } } } }, "responses": { "200": { "description": "Email address updated. For `invited` users, the invitation email has also been re-sent to the new address." }, "400": { "description": "Validation error or user is in a state that does not allow email change (only `active` and `invited` are accepted). See response body for details." }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" }, "409": { "description": "Email address is used by another user" }, "422": { "description": "Failed to update user's email address in the underlying user store (transient downstream failure \u2014 safe to retry)." }, "502": { "description": "Partial failure: the email address was updated successfully but the follow-up invitation re-send failed. The new email is in effect; retry the invitation resend out-of-band." } } } }, "/api/organisation-unit/{unitId}": { "get": { "tags": [ "Organisation Units" ], "summary": "Returns the specified organisation unit along with all its child units.", "operationId": "get_organisation-unit-get", "parameters": [ { "name": "unitId", "in": "path", "description": "Organisation unit internal or external ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organisation Unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUnit" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Target organisation unit not found" } } }, "delete": { "tags": [ "Organisation Units" ], "summary": "Removes an organisation unit from the structure.", "operationId": "delete_organisation-unit-delete-unit", "parameters": [ { "name": "unitId", "in": "path", "description": "Organisation unit internal or external ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organisation unit removed" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Organisation unit not found" } } }, "patch": { "tags": [ "Organisation Units" ], "summary": "Updates the name of a selected existing organisation unit.", "operationId": "patch_organisation-unit-modify-unit", "parameters": [ { "name": "unitId", "in": "path", "description": "Organisation unit internal or external ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUnitUpdate" } } } }, "responses": { "200": { "description": "Workspace's organisation structure after modification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationStructure" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Target organisation unit not found" } }, "security": [ { "apiKey": [] } ] } }, "/api/organisation-unit/{unitId}/move-to/{parentId}": { "patch": { "tags": [ "Organisation Units" ], "summary": "Moves an organisation unit to a new parent unit.", "operationId": "patch_organisation-unit-move-unit", "parameters": [ { "name": "unitId", "in": "path", "description": "Organisation unit internal or external ID", "required": true, "schema": { "type": "string" } }, { "name": "parentId", "in": "path", "description": "New parent unit internal or external ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workspace's organisation structure after modification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationStructure" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Organisation unit or target unit not found" }, "422": { "description": "Failed to move organisation unit. See response for details" } }, "security": [ { "apiKey": [] } ] } }, "/api/organisation-units": { "get": { "tags": [ "Organisation Units" ], "summary": "Returns the complete structure of organisation units within a workspace.", "operationId": "get_organisation-unit-structure", "responses": { "200": { "description": "Organisation unit structure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationStructure" } } } }, "401": { "description": "Invalid or inactive API key" } }, "security": [ { "apiKey": [] } ] }, "post": { "tags": [ "Organisation Units" ], "summary": "Creates a new organisation unit. To create a top-level unit, leave the 'parentId' field empty.", "operationId": "post_organisation-unit-create-unit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUnitCreate" } } } }, "responses": { "201": { "description": "Workspace's organisation structure with new node", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationStructure" } } } }, "400": { "description": "Input validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "422": { "description": "Processing error. See response for details" }, "404": { "description": "Parent organisation unit not found" } }, "security": [ { "apiKey": [] } ] } }, "/ping": { "get": { "tags": [ "Health check" ], "summary": "Checks whether the API can respond. No authentication is needed.", "operationId": "get_ping", "responses": { "200": { "description": "pong" } }, "security": [] } }, "/api/settings/custom-fields": { "get": { "tags": [ "Settings" ], "summary": "Lists all custom fields in the workspace.", "operationId": "get_custom_fields", "responses": { "200": { "description": "Custom fields", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } } } } }, "401": { "description": "Invalid or inactive API key" } }, "security": [ { "apiKey": [] } ] } }, "/api/user/{userId}/group/{groupId}": { "post": { "tags": [ "User groups" ], "summary": "Adds a user to a user group.", "operationId": "post_add-group-member", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "User group identifier", "required": true, "schema": { "type": "string" }, "example": "user-group-1" } ], "responses": { "200": { "description": "User details after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Invalid custom field" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group or user not found" }, "409": { "description": "User was already a member of the group" }, "422": { "description": "User is not active" } } }, "delete": { "tags": [ "User groups" ], "summary": "Removes a user from the group.", "operationId": "delete_remove-group-member", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "description": "User group identifier", "required": true, "schema": { "type": "string" }, "example": "user-group-1" } ], "responses": { "200": { "description": "User details after the change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "Group or user not found" }, "422": { "description": "User is not active" } } } }, "/api/user/{userId}/invite-cancel": { "delete": { "tags": [ "Invitations" ], "summary": "Cancels a previously sent invitation.", "operationId": "delete_user_invite_cancel", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation successfully cancelled" }, "401": { "description": "Invalid or inactive API key" }, "422": { "description": "Input already managed" }, "404": { "description": "User does not exist or is unavailable" } } } }, "/api/user/{userId}/invite-resend": { "patch": { "tags": [ "Invitations" ], "summary": "Resends an invitation to a user if the existing invitation is in a 'SENT' status.", "operationId": "patch_user_invite_resend", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation has been successfully resent" }, "401": { "description": "Invalid or inactive API key" }, "422": { "description": "Processing error. See response for details" }, "404": { "description": "User does not exist or is unavailable" } } } }, "/api/user/{userId}": { "get": { "tags": [ "Users" ], "summary": "Returns the details of the requested user.", "operationId": "get_get_user", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } }, "put": { "tags": [ "Users" ], "summary": "Updates the email address of the requested user. After the update, the user will be identified by the new email address.", "description": "Allowed for users in `active` or `invited` state. For `invited` users the existing invitation is updated to the new email and the invitation email is automatically re-sent to that address \u2014 no separate resend request is required. Users in any other state are rejected with `400`. An equivalent endpoint scoped at the invitation URL is available at `PUT /api/invitation/{userId}/email-address` (Invitations).", "operationId": "put_update_email_address", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailAddressJsonRequest" } } } }, "responses": { "200": { "description": "Email address updated. For `invited` users, the invitation email has also been re-sent to the new address." }, "400": { "description": "Validation error or user is in a state that does not allow email change (only `active` and `invited` are accepted). See response body for details." }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" }, "409": { "description": "Email address is used by another user" }, "422": { "description": "Failed to update user's email address in the underlying user store (transient downstream failure \u2014 safe to retry)." }, "502": { "description": "Partial failure: the email address was updated successfully but the follow-up invitation re-send failed (only emitted on the `invited`-user path). The new email is in effect; retry the invitation resend out-of-band." } } }, "patch": { "tags": [ "Users" ], "summary": "Updates the defined details of the requested user.", "description": "Updates the fields you provide.\n\nWhen updating `customFields`, include every value you want to keep. Omitting `customFields` or sending an empty object leaves existing values unchanged.\n\nOmit `expireDate` to keep the current date. Send `null` to clear it.\n\nSee [Custom fields](/doc/resources#custom-fields) for details.", "operationId": "patch_update_user", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdate" } } } }, "responses": { "200": { "description": "Modified user details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } } }, "/api/user/{userId}/organisation-unit": { "delete": { "tags": [ "Users" ], "summary": "Removes the user from the organisation unit to which they are assigned.", "operationId": "delete_clear_user_ou", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Modified user details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } }, "patch": { "tags": [ "Users" ], "summary": "Updates the user's organisation unit assignment.", "operationId": "patch_move_user_to_ou", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignOrganisationUnitRequest" } } } }, "responses": { "200": { "description": "Modified user details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User or target organisation unit does not exist or is unavailable" } } } }, "/api/user/{userId}/roles": { "patch": { "tags": [ "Users" ], "summary": "Updates the user roles.", "description": "Replaces the assigned roles. Include every role you want to keep.\n\nFor Manager, include at least one existing organisation unit in `managedOrganisationUnits`.\nFor learner without Manager, send `managedOrganisationUnits: []`.\nTo keep both roles, send `roles: [learner, manager]`.\n\nTo assign Manager to an invited user, use `PATCH /api/invitation/{userId}/roles`.", "operationId": "patch_update_user_roles", "parameters": [ { "name": "userId", "in": "path", "description": "User internal UUID or email address", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRolesRequest" }, "examples": { "learner": { "summary": "Learner only", "description": "Replaces all current roles with learner. Any other role is removed.", "value": { "roles": [ "learner" ], "managedOrganisationUnits": [] } }, "manager": { "summary": "Manager only", "description": "Replaces all current roles with manager. Replace the organisation-unit ID with an existing one. Include learner in roles too if that role should be retained.", "value": { "roles": [ "manager" ], "managedOrganisationUnits": [ "existing-organisation-unit-id" ] } } } } } }, "responses": { "200": { "description": "User roles updated" }, "400": { "description": "Validation error. See response for details" }, "401": { "description": "Invalid or inactive API key" }, "404": { "description": "User does not exist or is unavailable" } } } }, "/api/users/invite": { "post": { "tags": [ "Invitations" ], "summary": "Creates a user profile and sends an invitation to the user based on predefined parameters.", "description": "Creates an invitation and sends an invitation email.\n\nReplace the example email address and add any custom fields required by your workspace.\n\nIf the request times out, check whether the invitation was created before sending it again.", "operationId": "post_user_invite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationCreate" }, "examples": { "learner": { "summary": "Learner without organisation-unit or group assignments", "description": "Replace the placeholder email and name. Add any custom fields required by your workspace.", "value": { "emailAddress": "learner@example.com", "firstName": "Example", "lastName": "Learner", "roles": [ "learner" ], "organisationUnit": null, "expireDate": null, "managedOrganisationUnits": [], "workspaceGroups": [] } }, "manager": { "summary": "Manager of an existing organisation unit", "description": "Replace the placeholder email, name and organisation-unit ID. Add any custom fields required by your workspace.", "value": { "emailAddress": "manager@example.com", "firstName": "Example", "lastName": "Manager", "roles": [ "manager" ], "organisationUnit": null, "expireDate": null, "managedOrganisationUnits": [ "existing-organisation-unit-id" ], "workspaceGroups": [] } } } } } }, "responses": { "201": { "description": "Invitation successfully sent", "content": { "application/json": { "schema": { "type": "string", "example": "Invitation successfully sent" } } } }, "400": { "description": "Input validation error. See response body for details" }, "401": { "description": "Invalid or inactive API key" }, "422": { "description": "Processing error. See response for details" } } } }, "/api/users": { "get": { "tags": [ "Users" ], "summary": "Returns a paginated list of users.", "operationId": "get_list_users", "parameters": [ { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "default": "1" } }, { "name": "pageSize", "in": "query", "description": "Page size", "required": false, "schema": { "type": "integer", "default": "12" } }, { "name": "sortDirection", "in": "query", "description": "Sort direction", "required": false, "schema": { "$ref": "#/components/schemas/SortDirection2" } }, { "name": "sortColumn", "in": "query", "description": "Column used to sort the list", "required": false, "schema": { "type": "string", "default": "lastName", "enum": [ "lastName", "emailAddress" ] } } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } }, "401": { "description": "Invalid or inactive API key" } }, "security": [ { "apiKey": [] } ] } }, "/api/whoiam": { "get": { "tags": [ "Health check" ], "summary": "Validates the API key and returns its workspace, status and issue date.", "operationId": "get_api_key_validation", "responses": { "200": { "description": "API key details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyDetails" } } } }, "401": { "description": "Unknown or inactive API key" } } } } }, "components": { "schemas": { "ApiKeyDetails": { "properties": { "key": { "type": "string", "example": "95D5YGC2BMYXY25C432SEZKLIQX8AYAY6KNBEI7D" }, "workspace": { "description": "Workspace ID", "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "active" }, "issuedAt": { "type": "string", "format": "date-time" } }, "type": "object" }, "AssignOrganisationUnitRequest": { "required": [ "organisationUnit" ], "properties": { "organisationUnit": { "description": "Organisation unit internal or external ID", "type": "string" } }, "type": "object" }, "CreateGroupRequest": { "required": [ "id", "name" ], "properties": { "id": { "type": "string", "example": "user-group-1" }, "name": { "type": "string", "example": "Managers" } }, "type": "object" }, "CustomField": { "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "customValidation": { "type": "object", "nullable": true }, "help": { "type": "string" }, "required": { "type": "boolean" } }, "type": "object" }, "CustomFieldsValue": { "properties": { "number-type-custom-field-name": { "description": "Integer numbers", "type": "integer", "example": 123 }, "date-type-custom-field-name": { "description": "Date values", "type": "string", "format": "date", "example": "2023-03-15" }, "email-type-custom-field-name": { "description": "Valid email address", "type": "string", "format": "email", "example": "alternate.address@example.com" }, "az-type-custom-field-name": { "description": "Letters only", "type": "string", "example": "LoremIpsumDolorSit" }, "text-type-custom-field-name": { "description": "Any text value", "type": "string", "example": "Lorem Ipsum Dolor Sit" } }, "type": "object" }, "GroupResponse": { "properties": { "id": { "type": "string", "example": "group-id-1" }, "internalId": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Managers" } }, "type": "object" }, "InvitationCreate": { "required": [ "emailAddress", "firstName", "lastName", "roles" ], "properties": { "emailAddress": { "type": "string", "format": "email", "example": "john.doe@example.com" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRole" }, "minItems": 1 }, "customFields": { "$ref": "#/components/schemas/CustomFieldsValue" }, "organisationUnit": { "description": "Organisation unit external or internal ID", "type": "string", "example": "target-organisation-unit-id", "nullable": true }, "expireDate": { "description": "Optional expiry date; must be today or later (UTC)", "type": "string", "format": "date", "example": null, "nullable": true }, "managedOrganisationUnits": { "description": "List of managed organisation units", "type": "array", "items": { "type": "string", "example": "managed-organisation-unit-id" }, "nullable": true }, "workspaceGroups": { "description": "List of user groups", "type": "array", "items": { "type": "string", "example": "user-group-id-1" }, "nullable": true } }, "type": "object" }, "OrganisationStructure": { "properties": { "name": { "type": "string" }, "structure": { "type": "array", "items": { "$ref": "#/components/schemas/OrganisationUnit" }, "default": [] } }, "type": "object" }, "OrganisationUnit": { "properties": { "id": { "type": "string" }, "internalId": { "type": "string", "format": "uuid" }, "parent": { "type": "string", "default": null, "nullable": true }, "parentInternalId": { "type": "string", "format": "uuid", "nullable": true }, "name": { "type": "string" }, "managers": { "description": "Organisation unit managers", "type": "array", "items": { "$ref": "#/components/schemas/OrganisationUnitManager" }, "default": [] }, "children": { "description": "Child units", "type": "array", "items": { "$ref": "#/components/schemas/OrganisationUnit" }, "default": [] } }, "type": "object" }, "OrganisationUnitCreate": { "required": [ "id", "name" ], "properties": {}, "type": "object" }, "OrganisationUnitManager": { "properties": { "userId": { "type": "string", "format": "uuid" }, "userProfileId": { "type": "string", "format": "uuid" }, "emailAddress": { "type": "string", "format": "email" } }, "type": "object" }, "OrganisationUnitSimpleDTO": { "properties": { "internalId": { "description": "Organisation unit internal ID", "type": "string", "format": "uuid" }, "externalId": { "description": "Organisation unit external ID", "type": "string", "example": "ou-id-1" }, "parentInternalId": { "description": "Parent Organisation unit internal ID", "type": "string", "format": "uuid", "nullable": true }, "parentExternalId": { "description": "Parent Organisation unit external ID", "type": "string", "example": "ou-id-0", "nullable": true }, "name": { "description": "Organisation unit name", "type": "string", "example": "Sales" } }, "type": "object" }, "OrganisationUnitUpdate": { "properties": {}, "type": "object" }, "Pagination": { "properties": { "page": { "description": "Current page number", "type": "integer", "format": "int32", "example": "3" }, "pageSize": { "description": "Maximum number of items per page", "type": "integer", "format": "int32", "example": "12" }, "totalPages": { "description": "Total number of pages", "type": "integer", "format": "int32", "default": 1, "example": "8" }, "totalResults": { "description": "Total number of elements", "type": "integer", "format": "int32" }, "currentPage": { "description": "Encoded, persistent URL to the current page", "type": "string", "example": "/api/samples/eyJwYWdpbmF0aW9uIjogeyJwYWdlIjogMywgInBhZ2VTaXplIiA6IDEyfSwgIm9yZGVyIjogeyJjb2x1bW4iIDogIm5hbWUiLCAiZGVzY2VuZGluZyIgOiBmYWxzZX0sICJmaWx0ZXIiIDogInNwZWNpZmljIHNhbXBsZSJ9" }, "nextPage": { "description": "URL to next page (in this example: 4th page)", "type": "string", "example": "/api/samples/eyJwYWdpbmF0aW9uIjogeyJwYWdlIjogNCwgInBhZ2VTaXplIiA6IDEyfSwgIm9yZGVyIjogeyJjb2x1bW4iIDogIm5hbWUiLCAiZGVzY2VuZGluZyIgOiBmYWxzZX0sICJmaWx0ZXIiIDogInNwZWNpZmljIHNhbXBsZSJ9", "nullable": true }, "previousPage": { "description": "URL to previous page (in this example: 2nd page)", "type": "string", "example": "/api/samples/eyJwYWdpbmF0aW9uIjogeyJwYWdlIjogMiwgInBhZ2VTaXplIiA6IDEyfSwgIm9yZGVyIjogeyJjb2x1bW4iIDogIm5hbWUiLCAiZGVzY2VuZGluZyIgOiBmYWxzZX0sICJmaWx0ZXIiIDogInNwZWNpZmljIHNhbXBsZSJ9", "nullable": true } }, "type": "object" }, "SortDirection": { "type": "string", "enum": [ "asc", "desc" ] }, "SortDirection2": { "type": "string", "enum": [ "asc", "desc" ] }, "UpdateEmailAddressJsonRequest": { "required": [ "newEmailAddress" ], "properties": { "newEmailAddress": { "type": "string" } }, "type": "object" }, "UpdateGroupRequest": { "required": [ "name" ], "properties": { "name": { "description": "New group name", "type": "string", "example": "Sales" } }, "type": "object" }, "UpdateInvitationCustomFieldsRequest": { "required": [ "customFields" ], "properties": { "customFields": { "$ref": "#/components/schemas/CustomFieldsValue" } }, "type": "object" }, "UpdateInvitationUserDataRequest": { "properties": { "firstName": { "description": "User's first name", "type": "string", "example": "John" }, "lastName": { "description": "User's last name", "type": "string", "example": "Doe" }, "expireDate": { "type": "string", "format": "date", "default": "0001-01-01", "nullable": true } }, "type": "object" }, "UpdateInvitedUserGroupsRequest": { "required": [ "workspaceGroups" ], "properties": {}, "type": "object" }, "UpdateUserRolesRequest": { "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRole" }, "minItems": 1 }, "managedOrganisationUnits": { "description": "List of managed organisation units", "type": "array", "items": { "type": "string", "example": "managed-organisation-unit-id" }, "nullable": true } }, "type": "object" }, "User": { "properties": { "emailAddress": { "type": "string", "format": "email" }, "id": { "type": "string", "format": "uuid" }, "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Doe" }, "status": { "type": "string", "example": "active" }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "learner", "manager" ] }, "expireDate": { "type": "string", "format": "date" }, "organisationUnit": { "$ref": "#/components/schemas/OrganisationUnitSimpleDTO" }, "customValues": { "$ref": "#/components/schemas/CustomFieldsValue" } }, "type": "object" }, "UserList": { "properties": { "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "UserUpdate": { "properties": { "firstName": { "description": "User's first name", "type": "string", "default": null, "example": "John", "nullable": true }, "lastName": { "description": "User's last name", "type": "string", "default": null, "example": "Doe", "nullable": true }, "expireDate": { "type": "string", "format": "date", "default": "0001-01-01", "nullable": true }, "customFields": { "default": null, "externalDocs": { "url": "/doc/resources#custom-fields" }, "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/CustomFieldsValue" } ] } }, "type": "object" }, "WorkspaceRole": { "type": "string", "enum": [ "learner", "admin", "manager" ] } }, "parameters": { "page": { "name": "page", "in": "query", "description": "Current page number", "required": false, "schema": { "type": "integer", "format": "int32", "default": 1, "minimum": 1 } }, "pageSize": { "name": "pageSize", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "format": "int32", "default": 12, "minimum": 1 } }, "sortDescending": { "name": "descending", "in": "query", "description": "Change the default sort direction to `descending`", "required": false, "schema": { "type": "boolean", "default": false } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Enter the raw API key for this workspace. Do not enter an SSO token. See /doc/authentication for header compatibility and troubleshooting.", "name": "Authorization", "in": "header" } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Health check", "description": "Check service availability and API key details", "externalDocs": { "description": "Read more about service health", "url": "/doc/health" } }, { "name": "Invitations" }, { "name": "Organisation Units" }, { "name": "User groups" }, { "name": "Settings" }, { "name": "Users" } ] }