dandri/matrix-authentication-service
1
0
Fork 0
mirror of https://github.com/element-hq/matrix-authentication-service.git synced 2026-03-30 21:35:56 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
62e01883b60cbcc78fffd99a2efc97e783f4a6c5
matrix-authentication-service/docs/api/spec.json
Quentin Gliech 29d6383c5d admin: rename the can_request_admin field to admin
2024-08-07 20:13:43 +02:00

1603 lines
50 KiB
JSON
Raw Blame History

{
"openapi": "3.1.0",
"info": {
"title": "Matrix Authentication Service admin API",
"version": ""
},
"servers": [
{
"url": "{base}",
"variables": {
"base": {
"default": "/",
"description": null
}
}
}
],
"paths": {
"/api/admin/v1/oauth2-sessions": {
"get": {
"tags": [
"oauth2-session"
],
"summary": "List OAuth 2.0 sessions",
"description": "Retrieve a list of OAuth 2.0 sessions.\nNote that by default, all sessions, including finished ones are returned, with the oldest first.\nUse the `filter[status]` parameter to filter the sessions by their status and `page[last]` parameter to retrieve the last N sessions.",
"operationId": "listOAuth2Sessions",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[user]",
"description": "Retrieve the items for the given user",
"schema": {
"description": "Retrieve the items for the given user",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[client]",
"description": "Retrieve the items for the given client",
"schema": {
"description": "Retrieve the items for the given client",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[user-session]",
"description": "Retrieve the items started from the given browser session",
"schema": {
"description": "Retrieve the items started from the given browser session",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[scope]",
"description": "Retrieve the items with the given scope",
"schema": {
"description": "Retrieve the items with the given scope",
"default": [],
"type": "array",
"items": {
"type": "string"
}
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all sessions, including finished ones.\n\n* `active`: Only retrieve active sessions\n\n* `finished`: Only retrieve finished sessions",
"schema": {
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all sessions, including finished ones.\n\n* `active`: Only retrieve active sessions\n\n* `finished`: Only retrieve finished sessions",
"$ref": "#/components/schemas/OAuth2SessionStatus",
"nullable": true
},
"style": "form"
}
],
"responses": {
"200": {
"description": "Paginated response of OAuth 2.0 sessions",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedResponse_for_OAuth2Session"
},
"example": {
"meta": {
"count": 42
},
"data": [
{
"type": "oauth2-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_session_id": "030C1G60R30C1G60R30C1G60R3",
"client_id": "040G2081040G2081040G208104",
"scope": "openid",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
}
},
{
"type": "oauth2-session",
"id": "02081040G2081040G2081040G2",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": null,
"user_session_id": null,
"client_id": "050M2GA1850M2GA1850M2GA185",
"scope": "urn:mas:admin",
"user_agent": null,
"last_active_at": null,
"last_active_ip": null
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/02081040G2081040G2081040G2"
}
},
{
"type": "oauth2-session",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": "1970-01-01T00:00:00Z",
"user_id": "040G2081040G2081040G208104",
"user_session_id": "050M2GA1850M2GA1850M2GA185",
"client_id": "060R30C1G60R30C1G60R30C1G6",
"scope": "urn:matrix:org.matrix.msc2967.client:api:*",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/030C1G60R30C1G60R30C1G60R3"
}
}
],
"links": {
"self": "/api/admin/v1/oauth2-sessions?page[first]=3",
"first": "/api/admin/v1/oauth2-sessions?page[first]=3",
"last": "/api/admin/v1/oauth2-sessions?page[last]=3",
"next": "/api/admin/v1/oauth2-sessions?page[after]=030C1G60R30C1G60R30C1G60R3&page[first]=3"
}
}
}
}
},
"404": {
"description": "User was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
},
"400": {
"description": "Invalid scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Invalid scope \"not a valid scope\" in filter parameters"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/oauth2-sessions/{id}": {
"get": {
"tags": [
"oauth2-session"
],
"summary": "Get an OAuth 2.0 session",
"operationId": "getOAuth2Session",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "OAuth 2.0 session was found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_OAuth2Session"
},
"example": {
"data": {
"type": "oauth2-session",
"id": "01040G2081040G2081040G2081",
"attributes": {
"created_at": "1970-01-01T00:00:00Z",
"finished_at": null,
"user_id": "02081040G2081040G2081040G2",
"user_session_id": "030C1G60R30C1G60R30C1G60R3",
"client_id": "040G2081040G2081040G208104",
"scope": "openid",
"user_agent": "Mozilla/5.0",
"last_active_at": "1970-01-01T00:00:00Z",
"last_active_ip": "127.0.0.1"
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/oauth2-sessions/01040G2081040G2081040G2081"
}
}
}
}
},
"404": {
"description": "OAuth 2.0 session was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "OAuth 2.0 session ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users": {
"get": {
"tags": [
"user"
],
"summary": "List users",
"operationId": "listUsers",
"parameters": [
{
"in": "query",
"name": "page[before]",
"description": "Retrieve the items before the given ID",
"schema": {
"description": "Retrieve the items before the given ID",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[after]",
"description": "Retrieve the items after the given ID",
"schema": {
"description": "Retrieve the items after the given ID",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[first]",
"description": "Retrieve the first N items",
"schema": {
"description": "Retrieve the first N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "page[last]",
"description": "Retrieve the last N items",
"schema": {
"description": "Retrieve the last N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[admin]",
"description": "Retrieve users with (or without) the `admin` flag set",
"schema": {
"description": "Retrieve users with (or without) the `admin` flag set",
"type": "boolean",
"nullable": true
},
"style": "form"
},
{
"in": "query",
"name": "filter[status]",
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users",
"schema": {
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users",
"$ref": "#/components/schemas/UserStatus",
"nullable": true
},
"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,
"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,
"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",
"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"
}
}
}
}
}
}
},
"post": {
"tags": [
"user"
],
"summary": "Create a new user",
"operationId": "createUser",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "User was created",
"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,
"admin": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
}
}
}
},
"400": {
"description": "Username is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Username is not valid"
}
]
}
}
}
},
"409": {
"description": "Username is reserved by the homeserver",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Username is reserved by the homeserver"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}": {
"get": {
"tags": [
"user"
],
"summary": "Get a user",
"operationId": "getUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"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,
"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/{id}/set-password": {
"post": {
"tags": [
"user"
],
"summary": "Set the password for a user",
"operationId": "setUserPassword",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetUserPasswordRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
}
}
}
},
"400": {
"description": "Password is too weak",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Password is too weak"
}
]
}
}
}
},
"403": {
"description": "Password auth is disabled in the server configuration",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "Password auth is disabled"
}
]
}
}
}
},
"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": {
"tags": [
"user"
],
"summary": "Get a user by its username (localpart)",
"operationId": "getUserByUsername",
"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,
"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"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/set-admin": {
"post": {
"tags": [
"user"
],
"summary": "Set whether a user can request admin",
"description": "Calling this endpoint will not have any effect on existing sessions, meaning that their existing sessions will keep admin access if they were granted it.",
"operationId": "userSetAdmin",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSetAdminRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "User had admin privileges set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "02081040G2081040G2081040G2",
"attributes": {
"username": "bob",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": null,
"admin": true
},
"links": {
"self": "/api/admin/v1/users/02081040G2081040G2081040G2"
}
},
"links": {
"self": "/api/admin/v1/users/02081040G2081040G2081040G2/set-admin"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/deactivate": {
"post": {
"tags": [
"user"
],
"summary": "Deactivate a user",
"description": "Calling this endpoint will lock and deactivate the user, preventing them from doing any action.\nThis invalidates any existing session, and will ask the homeserver to make them leave all rooms.",
"operationId": "deactivateUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was deactivated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"username": "charlie",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": "1970-01-01T00:00:00Z",
"admin": false
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3/deactivate"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/lock": {
"post": {
"tags": [
"user"
],
"summary": "Lock a user",
"description": "Calling this endpoint will lock the user, preventing them from doing any action.\nThis DOES NOT invalidate any existing session, meaning that all their existing sessions will work again as soon as they get unlocked.",
"operationId": "lockUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was locked",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SingleResponse_for_User"
},
"example": {
"data": {
"type": "user",
"id": "030C1G60R30C1G60R30C1G60R3",
"attributes": {
"username": "charlie",
"created_at": "1970-01-01T00:00:00Z",
"locked_at": "1970-01-01T00:00:00Z",
"admin": false
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3"
}
},
"links": {
"self": "/api/admin/v1/users/030C1G60R30C1G60R30C1G60R3/lock"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 not found"
}
]
}
}
}
}
}
}
},
"/api/admin/v1/users/{id}/unlock": {
"post": {
"tags": [
"user"
],
"summary": "Unlock a user",
"operationId": "unlockUser",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"title": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
},
"style": "simple"
}
],
"responses": {
"200": {
"description": "User was unlocked",
"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,
"admin": false
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081"
}
},
"links": {
"self": "/api/admin/v1/users/01040G2081040G2081040G2081/unlock"
}
}
}
}
},
"404": {
"description": "User ID not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"errors": [
{
"title": "User ID 00000000000000000000000000 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",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"page[after]": {
"description": "Retrieve the items after the given ID",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"page[first]": {
"description": "Retrieve the first N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
},
"page[last]": {
"description": "Retrieve the last N items",
"type": "integer",
"format": "uint",
"minimum": 1.0,
"nullable": true
}
}
},
"ULID": {
"title": "ULID",
"description": "A ULID as per https://github.com/ulid/spec",
"examples": [
"01ARZ3NDEKTSV4RRFFQ69G5FAV",
"01J41912SC8VGAQDD50F6APK91"
],
"type": "string",
"pattern": "^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$"
},
"OAuth2SessionFilter": {
"type": "object",
"properties": {
"filter[user]": {
"description": "Retrieve the items for the given user",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"filter[client]": {
"description": "Retrieve the items for the given client",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"filter[user-session]": {
"description": "Retrieve the items started from the given browser session",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"filter[scope]": {
"description": "Retrieve the items with the given scope",
"default": [],
"type": "array",
"items": {
"type": "string"
}
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all sessions, including finished ones.\n\n* `active`: Only retrieve active sessions\n\n* `finished`: Only retrieve finished sessions",
"$ref": "#/components/schemas/OAuth2SessionStatus",
"nullable": true
}
}
},
"OAuth2SessionStatus": {
"type": "string",
"enum": [
"active",
"finished"
]
},
"PaginatedResponse_for_OAuth2Session": {
"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_OAuth2Session"
}
},
"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_OAuth2Session": {
"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",
"$ref": "#/components/schemas/ULID"
},
"attributes": {
"description": "The attributes of the resource",
"$ref": "#/components/schemas/OAuth2Session"
},
"links": {
"description": "Related links",
"$ref": "#/components/schemas/SelfLinks"
}
}
},
"OAuth2Session": {
"description": "A OAuth 2.0 session",
"type": "object",
"required": [
"client_id",
"created_at",
"scope"
],
"properties": {
"created_at": {
"description": "When the object was created",
"type": "string",
"format": "date-time"
},
"finished_at": {
"description": "When the session was finished",
"type": "string",
"format": "date-time",
"nullable": true
},
"user_id": {
"description": "The ID of the user who owns the session",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"user_session_id": {
"description": "The ID of the browser session which started this session",
"$ref": "#/components/schemas/ULID",
"nullable": true
},
"client_id": {
"description": "The ID of the client which requested this session",
"$ref": "#/components/schemas/ULID"
},
"scope": {
"description": "The scope granted for this session",
"type": "string"
},
"user_agent": {
"description": "The user agent string of the client which started this session",
"type": "string",
"nullable": true
},
"last_active_at": {
"description": "The last time the session was active",
"type": "string",
"format": "date-time",
"nullable": true
},
"last_active_ip": {
"description": "The last IP address used by the session",
"type": "string",
"format": "ip",
"nullable": true
}
}
},
"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",
"nullable": true
},
"prev": {
"description": "The link to the previous page of results\n\nOnly present if there is a previous page",
"type": "string",
"nullable": true
}
}
},
"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": "The ID of the resource",
"$ref": "#/components/schemas/ULID"
}
}
},
"SingleResponse_for_OAuth2Session": {
"description": "A top-level response with a single resource",
"type": "object",
"required": [
"data",
"links"
],
"properties": {
"data": {
"$ref": "#/components/schemas/SingleResource_for_OAuth2Session"
},
"links": {
"$ref": "#/components/schemas/SelfLinks"
}
}
},
"UserFilter": {
"type": "object",
"properties": {
"filter[admin]": {
"description": "Retrieve users with (or without) the `admin` flag set",
"type": "boolean",
"nullable": true
},
"filter[status]": {
"description": "Retrieve the items with the given status\n\nDefaults to retrieve all users, including locked ones.\n\n* `active`: Only retrieve active users\n\n* `locked`: Only retrieve locked users",
"$ref": "#/components/schemas/UserStatus",
"nullable": true
}
}
},
"UserStatus": {
"type": "string",
"enum": [
"active",
"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"
}
}
},
"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",
"$ref": "#/components/schemas/ULID"
},
"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": [
"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",
"format": "date-time",
"nullable": true
},
"admin": {
"description": "Whether the user can request admin privileges.",
"type": "boolean"
}
}
},
"AddUserRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users` endpoint",
"type": "object",
"required": [
"username"
],
"properties": {
"username": {
"description": "The username of the user to add.",
"type": "string"
},
"skip_homeserver_check": {
"description": "Skip checking with the homeserver whether the username is available.\n\nUse this with caution! The main reason to use this, is when a user used by an application service needs to exist in MAS to craft special tokens (like with admin access) for them",
"default": false,
"type": "boolean"
}
}
},
"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"
}
}
},
"SetUserPasswordRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users/:id/set-password` endpoint",
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"description": "The password to set for the user",
"examples": [
"hunter2"
],
"type": "string"
},
"skip_password_check": {
"description": "Skip the password complexity check",
"type": "boolean",
"nullable": true
}
}
},
"UsernamePathParam": {
"type": "object",
"required": [
"username"
],
"properties": {
"username": {
"description": "The username (localpart) of the user to get",
"type": "string"
}
}
},
"UserSetAdminRequest": {
"title": "JSON payload for the `POST /api/admin/v1/users/:id/set-admin` endpoint",
"type": "object",
"required": [
"admin"
],
"properties": {
"admin": {
"description": "Whether the user can request admin privileges.",
"type": "boolean"
}
}
}
}
},
"security": [
{
"oauth2": [
"urn:mas:admin"
]
}
],
"tags": [
{
"name": "oauth2-session",
"description": "Manage OAuth2 sessions"
},
{
"name": "user",
"description": "Manage users"
}
]
}
Reference in New Issue View Git Blame Copy Permalink