{ "openapi": "3.1.0", "info": { "title": "Wia REST API User reference", "description": "
A REST API to interact with Wia platform for user management for external IAM teams.

To get started, please ensure you have the correct permissions and appropriate client credentials. If you have not been provided client credentials, please contact your representative.

The API is organised around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.", "version": "v1" }, "components": { "securitySchemes": { "Organisation": { "type": "http", "description": "An application accessToken can be used", "scheme": "bearer", "bearerFormat": "Bearer" } }, "parameters": { "id": { "name": "id", "description": "Id of Object", "in": "path", "required": true, "schema": { "type": "string" } }, "organisationId": { "name": "organisation.id", "description": "Id of organisation", "in": "query", "required": false, "schema": { "type": "string" } }, "limit": { "name": "limit", "in": "query", "description": "Max number of rows to return", "required": false, "schema": { "type": "integer", "format": "int32", "example": 20 } }, "page": { "name": "page", "in": "query", "description": "Section of rows to return e.g. 0, 1 or 2", "required": false, "schema": { "type": "integer", "format": "int32" } }, "sort": { "name": "sort", "in": "query", "description": "Sort by Ascending or Descending order Default: DESC", "required": false, "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } }, "order": { "name": "order", "in": "query", "description": "Order by column e.g. id", "required": false, "schema": { "type": "string" } } }, "schemas": { "AccessToken": { "type": "object", "properties": { "token": { "type": "string", "example": "u_at_abc123def45678" }, "refreshToken": { "type": "string", "example": "u_rt_abc123def45678" }, "scope": { "type": "string", "description": "The Domain of the Access Token.", "example": "user" }, "expiresIn": { "type": "integer", "example": 36000 }, "createdAt": { "type": "integer", "example": 1642759067045 } } }, "Organisation": { "type": "object", "properties": { "id": { "type": "string", "example": "org_123abc456def" }, "name": { "type": "string", "example": "Test organisation" } } }, "OrganisationUser": { "type": "object", "properties": { "id": { "type": "string", "example": "ou_abc123def" }, "firstName": { "type": "string", "example": "Pina" }, "lastName": { "type": "string", "example": "Colada" }, "fullName": { "type": "string", "example": "Pina Colada" }, "userId": { "type": "string", "example": "usr_abc123def" }, "emailAddress": { "type": "string", "example": "pina.colada@wia.io" }, "isAdmin": { "type": "boolean", "example": false }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } } }, "Space": { "type": "object", "properties": { "id": { "type": "string", "example": "spc_abc123" }, "clientId": { "type": "string", "example": "client-specific-id" }, "name": { "type": "string", "example": "Test Space" }, "isPublic": { "type": "boolean", "example": false }, "disabled": { "type": "boolean", "example": false }, "avatar": { "type": "object", "properties": { "default": { "type": "string", "example": "1234-5342-5543-36AD" }, "url": { "type": "string", "example": "https://example.com/image" }, "thumbnail": { "type": "string", "example": "1234-5342-5543-36AD" } } }, "owner": { "type": "object", "properties": { "organisation": { "$ref": "#/components/schemas/Organisation" } } } } }, "Team": { "type": "object", "properties": { "id": { "type": "string", "example": "tem_123abc456def" }, "name": { "type": "string", "example": "Test organisation" }, "isAdmin": { "type": "boolean", "example": false }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } } } }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "example": "usr_123abc456def" }, "fullName": { "type": "string", "example": "John Doe" }, "emailAddress": { "type": "string", "example": "hello@example.com" }, "organisationUserId": { "type": "string", "example": "ou_123abcdeg456" } } }, "User": { "type": "object", "properties": { "id": { "type": "string", "example": "usr_abc123def" }, "firstName": { "type": "string", "example": "Pina" }, "lastName": { "type": "string", "example": "Colada" }, "fullName": { "type": "string", "example": "Pina Colada" }, "emailAddress": { "type": "string", "example": "pina.colada@wia.io" }, "isAdmin": { "type": "boolean", "example": false } } } }, "responses": { "NotFound": { "description": "The specified resource was not found." }, "BadRequest": { "description": "Bad Request." }, "Unauthorised": { "description": "Unauthorised." }, "ServerError": { "description": "Server Error." } } }, "servers": [ { "url": "https://api.wia.io/v1", "description": "Production" } ], "paths": { "/auth/token": { "post": { "tags": [ "Auth" ], "description": "Generate access token", "requestBody": { "content": { "application/json": { "schema": { "properties": { "clientId": { "type": "string", "description": "The client Id of the organisation" }, "clientSecret": { "type": "string", "description": "The client secret of the organisation" }, "refreshToken": { "type": "string", "description": "Required for refresh token" }, "grantType": { "type": "string", "enum": [ "client_credentials", "refresh_token" ], "description": "Define the type of grant" }, "scope": { "type": "string", "enum": [ "organisation" ], "description": "Define the access scope" } }, "required": [ "client_id", "client_secret" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/auth/token/revoke": { "post": { "tags": [ "Auth" ], "security": [ { "Organisation": [] } ], "description": "Revoke Token", "requestBody": { "content": { "application/json": { "schema": { "properties": { "token": { "description": "The token to revoke", "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "revoked": { "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/organisations/users/": { "post": { "tags": [ "Organisation" ], "security": [ { "Organisation": [] } ], "description": "Creates a user and adds them to an organisation", "requestBody": { "content": { "application/json": { "schema": { "properties": { "emailAddress": { "description": "Email Address of the user", "type": "string" }, "fullName": { "description": "Name of the user", "type": "string" }, "password": { "description": "Password for login", "type": "string" }, "loginViaSsoOnly": { "description": "Boolean to indicate if the user can only login via SSO (Password will be ignored)", "type": "string" } }, "required": [ "emailAddress" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUser" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/organisations/users": { "get": { "tags": [ "Organisation" ], "security": [ { "Organisation": [] } ], "description": "List users of an organisation", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OrganisationUser" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/organisations/{organisationUserId}": { "get": { "tags": [ "Organisation" ], "security": [ { "Organisation": [] } ], "description": "Retrieves organisation user with associated teams.", "parameters": [ { "name": "organisationUserId", "in": "path", "required": true, "description": "Id of the organisation user", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUser" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/organisations/users/{organisationUserId}": { "put": { "tags": [ "Organisation" ], "security": [ { "Organisation": [] } ], "description": "Updates details of an organisation user", "parameters": [ { "name": "organisationUserId", "in": "path", "required": true, "description": "Id of the organisation user to update", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isAdmin": { "description": "Update whether an organisation User is an Admin", "type": "boolean" } } } } } }, "responses": { "200": { "description": "Organisation user updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganisationUser" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Organisation" ], "security": [ { "Organisation": [] } ], "description": "Remove a user from an organisation and delete the user", "responses": { "200": { "description": "User successfully removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/teams/{id}": { "get": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Retrieves the details of a specific team using its Id.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the team to retrieve.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Deletes a team by its Id.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Id of the team to be deleted.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Team deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "description": "Indicates whether the deletion was successful.", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/teams/": { "get": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Retrieves a list of all teams in an organisation.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max number of results per page.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of teams retrieved successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Creates a new team in an organisation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organisationId": { "type": "string", "description": "Public Id of the organisation.", "example": "org123" }, "name": { "type": "string", "description": "Name of the team to create.", "example": "Marketing Team" } } } } } }, "responses": { "200": { "description": "Team created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/teams/{id}/members": { "post": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Adds a member to a specific team.", "parameters": [ { "name": "publicId", "in": "path", "required": true, "description": "Id of the team.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organisationUserId": { "type": "string", "description": "Id of the organisation User to add as a member.", "example": "ou_123abcder" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Removes member from a specific team.", "parameters": [ { "name": "publicId", "in": "path", "required": true, "description": "Id of the team.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organisationUserId": { "type": "string", "description": "Id of the user to remove as a member.", "example": "ou_123abcder" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/teams/{id}/members/{organisationUserId}": { "delete": { "tags": [ "Team" ], "security": [ { "Organisation": [] } ], "description": "Removes a specific member from a team.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Public Id of the team.", "schema": { "type": "string" } }, { "name": "organisationUserId", "in": "path", "required": true, "description": "Id of the organisation user to remove.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Member removed successfully." }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spaces": { "get": { "tags": [ "Space" ], "security": [ { "Organisation": [] } ], "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "name": "country", "description": "ISO 3166-1 alpha-3 country code", "in": "query", "schema": { "type": "string", "pattern": "^[A-Z]{3}$" }, "required": false } ], "description": "Retrieve list of all Spaces", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Space" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/spaces/{id}/alerts/users/{organisationUserId}": { "post": { "tags": [ "Space" ], "security": [ { "Organisation": [] } ], "description": "Add a user to space alerts", "parameters": [ { "name": "organisationUserId", "in": "path", "required": true, "description": "Id of the Organisation User to add to alerts", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User successfully added", "content": { "application/json": { "schema": { "type": "object", "properties": { "added": { "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Space" ], "security": [ { "Organisation": [] } ], "description": "Remove a user from space alerts", "responses": { "200": { "description": "User successfully removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "removed": { "type": "boolean", "example": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorised" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "tags": [ { "name": "Auth", "description": "Endpoints related to authentication, including login, token management, and authorisation." }, { "name": "Organisation", "description": "Endpoints that handle organisation-related operations, such as creation, management, and user assignments." }, { "name": "Team", "description": "Endpoints focused on team management, including creating teams, managing members, and related operations." }, { "name": "Space", "description": "Endpoints related to Spaces, including retrieval and management of space-specific settings and alerts." } ] }