{ "openapi": "3.1.0", "info": { "title": "Matrix Authentication Service admin API", "version": "" }, "servers": [ { "url": "{base}", "variables": { "base": { "default": "/", "description": null } } } ], "paths": { "/api/admin/v1/users": { "get": { "description": "List users", "parameters": [ { "in": "query", "name": "page[before]", "description": "Retrieve the items before the given ID", "schema": { "description": "Retrieve the items before the given ID", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "page[after]", "description": "Retrieve the items after the given ID", "schema": { "description": "Retrieve the items after the given ID", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "page[first]", "description": "Retrieve the first N items", "schema": { "description": "Retrieve the first N items", "type": [ "integer", "null" ], "format": "uint", "minimum": 1.0 }, "style": "form" }, { "in": "query", "name": "page[last]", "description": "Retrieve the last N items", "schema": { "description": "Retrieve the last N items", "type": [ "integer", "null" ], "format": "uint", "minimum": 1.0 }, "style": "form" }, { "in": "query", "name": "filter[can_request_admin]", "schema": { "type": [ "boolean", "null" ] }, "style": "form" }, { "in": "query", "name": "filter[status]", "schema": { "anyOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "type": "null" } ] }, "style": "form" } ], "responses": { "200": { "description": "Paginated response of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_for_User" }, "example": { "meta": { "count": 42 }, "data": [ { "type": "user", "id": "01040G2081040G2081040G2081", "attributes": { "username": "alice", "created_at": "1970-01-01T00:00:00Z", "locked_at": null, "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/01040G2081040G2081040G2081" } }, { "type": "user", "id": "02081040G2081040G2081040G2", "attributes": { "username": "bob", "created_at": "1970-01-01T00:00:00Z", "locked_at": null, "can_request_admin": true }, "links": { "self": "/api/admin/v1/users/02081040G2081040G2081040G2" } }, { "type": "user", "id": "030C1G60R30C1G60R30C1G60R3", "attributes": { "username": "charlie", "created_at": "1970-01-01T00:00:00Z", "locked_at": "1970-01-01T00:00:00Z", "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3" } } ], "links": { "self": "/api/admin/v1/users?page[first]=3", "first": "/api/admin/v1/users?page[first]=3", "last": "/api/admin/v1/users?page[last]=3", "next": "/api/admin/v1/users?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3" } } } } } } } }, "/api/admin/v1/users/{id}": { "get": { "description": "Get a user", "parameters": [ { "in": "path", "name": "id", "description": "A ULID as per https://github.com/ulid/spec", "required": true, "schema": { "title": "ULID", "description": "A ULID as per https://github.com/ulid/spec", "type": "string", "pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$" }, "style": "simple" } ], "responses": { "200": { "description": "User was found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleResponse_for_User" }, "example": { "data": { "type": "user", "id": "01040G2081040G2081040G2081", "attributes": { "username": "alice", "created_at": "1970-01-01T00:00:00Z", "locked_at": null, "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/01040G2081040G2081040G2081" } }, "links": { "self": "/api/admin/v1/users/01040G2081040G2081040G2081" } } } } }, "404": { "description": "User was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "title": "User ID 00000000000000000000000000 not found" } ] } } } } } } }, "/api/admin/v1/users/by-username/{username}": { "get": { "description": "Get a user by its username (localpart)", "parameters": [ { "in": "path", "name": "username", "description": "The username (localpart) of the user to get", "required": true, "schema": { "description": "The username (localpart) of the user to get", "type": "string" }, "style": "simple" } ], "responses": { "200": { "description": "User was found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleResponse_for_User" }, "example": { "data": { "type": "user", "id": "01040G2081040G2081040G2081", "attributes": { "username": "alice", "created_at": "1970-01-01T00:00:00Z", "locked_at": null, "can_request_admin": false }, "links": { "self": "/api/admin/v1/users/01040G2081040G2081040G2081" } }, "links": { "self": "/api/admin/v1/users/by-username/alice" } } } } }, "404": { "description": "User was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "errors": [ { "title": "User with username \"alice\" not found" } ] } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "clientCredentials": { "refreshUrl": "/oauth2/token", "tokenUrl": "/oauth2/token", "scopes": { "urn:mas:admin": "Grant access to the admin API" } }, "authorizationCode": { "authorizationUrl": "/authorize", "tokenUrl": "/oauth2/token", "refreshUrl": "/oauth2/token", "scopes": { "urn:mas:admin": "Grant access to the admin API" } } } } }, "schemas": { "PaginationParams": { "type": "object", "properties": { "page[before]": { "description": "Retrieve the items before the given ID", "type": [ "string", "null" ] }, "page[after]": { "description": "Retrieve the items after the given ID", "type": [ "string", "null" ] }, "page[first]": { "description": "Retrieve the first N items", "type": [ "integer", "null" ], "format": "uint", "minimum": 1.0 }, "page[last]": { "description": "Retrieve the last N items", "type": [ "integer", "null" ], "format": "uint", "minimum": 1.0 } } }, "FilterParams": { "type": "object", "properties": { "filter[can_request_admin]": { "type": [ "boolean", "null" ] }, "filter[status]": { "anyOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "type": "null" } ] } } }, "UserStatus": { "oneOf": [ { "description": "The user is active", "type": "string", "enum": [ "active" ] }, { "description": "The user is locked", "type": "string", "enum": [ "locked" ] } ] }, "PaginatedResponse_for_User": { "description": "A top-level response with a page of resources", "type": "object", "required": [ "data", "links", "meta" ], "properties": { "meta": { "description": "Response metadata", "$ref": "#/components/schemas/PaginationMeta" }, "data": { "description": "The list of resources", "type": "array", "items": { "$ref": "#/components/schemas/SingleResource_for_User" } }, "links": { "description": "Related links", "$ref": "#/components/schemas/PaginationLinks" } } }, "PaginationMeta": { "type": "object", "required": [ "count" ], "properties": { "count": { "description": "The total number of results", "type": "integer", "format": "uint", "minimum": 0.0 } } }, "SingleResource_for_User": { "description": "A single resource, with its type, ID, attributes and related links", "type": "object", "required": [ "attributes", "id", "links", "type" ], "properties": { "type": { "description": "The type of the resource", "type": "string" }, "id": { "description": "The ID of the resource", "type": "string" }, "attributes": { "description": "The attributes of the resource", "$ref": "#/components/schemas/User" }, "links": { "description": "Related links", "$ref": "#/components/schemas/SelfLinks" } } }, "User": { "description": "A user", "type": "object", "required": [ "can_request_admin", "created_at", "username" ], "properties": { "username": { "description": "The username (localpart) of the user", "type": "string" }, "created_at": { "description": "When the user was created", "type": "string", "format": "date-time" }, "locked_at": { "description": "When the user was locked. If null, the user is not locked.", "type": [ "string", "null" ], "format": "date-time" }, "can_request_admin": { "description": "Whether the user can request admin privileges.", "type": "boolean" } } }, "SelfLinks": { "description": "Related links", "type": "object", "required": [ "self" ], "properties": { "self": { "description": "The canonical link to the current resource", "type": "string" } } }, "PaginationLinks": { "description": "Related links", "type": "object", "required": [ "first", "last", "self" ], "properties": { "self": { "description": "The canonical link to the current page", "type": "string" }, "first": { "description": "The link to the first page of results", "type": "string" }, "last": { "description": "The link to the last page of results", "type": "string" }, "next": { "description": "The link to the next page of results\n\nOnly present if there is a next page", "type": [ "string", "null" ] }, "prev": { "description": "The link to the previous page of results\n\nOnly present if there is a previous page", "type": [ "string", "null" ] } } }, "ErrorResponse": { "description": "A top-level response with a list of errors", "type": "object", "required": [ "errors" ], "properties": { "errors": { "description": "The list of errors", "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "description": "A single error", "type": "object", "required": [ "title" ], "properties": { "title": { "description": "A human-readable title for the error", "type": "string" } } }, "UlidInPath": { "type": "object", "required": [ "id" ], "properties": { "id": { "title": "ULID", "description": "A ULID as per https://github.com/ulid/spec", "type": "string", "pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$" } } }, "SingleResponse_for_User": { "description": "A top-level response with a single resource", "type": "object", "required": [ "data", "links" ], "properties": { "data": { "$ref": "#/components/schemas/SingleResource_for_User" }, "links": { "$ref": "#/components/schemas/SelfLinks" } } }, "UsernamePathParam": { "type": "object", "required": [ "username" ], "properties": { "username": { "description": "The username (localpart) of the user to get", "type": "string" } } } } }, "security": [ { "oauth2": [ "urn:mas:admin" ] } ] }