{ "swagger": "2.0", "info": { "title": "Authentication service", "version": "0.1507.0", "description": "Send your API key as a bearer token: `Authorization: Bearer `." }, "consumes": [ "application/json" ], "produces": [ "application/json" ], "securityDefinitions": { "ApiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Your API key as a bearer token: `Authorization: Bearer `." } }, "security": [ { "ApiKey": [] } ], "paths": { "/authentication/v2/my/profile": { "get": { "operationId": "AuthenticationServiceV2_getMyProfile", "summary": "Get my profile", "tags": [ "Authentication Service" ], "description": "Gets the profile of the authenticated user.", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UserV2" }, "x-example": { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } } } }, "put": { "operationId": "AuthenticationServiceV2_updateMyProfile", "summary": "Update my profile", "tags": [ "Authentication Service" ], "description": "Updates the profile of the authenticated user.", "parameters": [ { "name": "updateMyProfileRequest", "in": "body", "schema": { "$ref": "#/definitions/UpdateMyProfileRequest" }, "required": true, "x-example": { "displayName": "" } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UserV2" }, "x-example": { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } } } } }, "/authentication/v2/my/settings": { "get": { "operationId": "AuthenticationServiceV2_getMySettings", "summary": "Get my settings", "tags": [ "Authentication Service" ], "description": "Gets the settings of the authenticated user.", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UserSettings" }, "x-example": { "defaultTimeRangeType": "DEFAULT", "appearance": "SYSTEM", "timezone": "LOCAL", "timeSeriesHoverTooltipConcise": true, "chartHoverTooltipMode": "VERBOSE", "defaultNumberFormats": { "data": { "sigFigs": 1, "displayOption": "SCIENTIFIC", "fixedDecimalPlaces": 1, "decimalPlaces": { "type": "fixed", "fixed": { "places": 1 } } } }, "relativeTimestampFormat": { "type": "temporalSubunits", "temporalSubunits": {} }, "vimModeEnabled": true, "defaultWorkbookVisibleInSearch": true } } } }, "put": { "operationId": "AuthenticationServiceV2_updateMySettings", "summary": "Update my settings", "tags": [ "Authentication Service" ], "description": "Updates the settings of the authenticated user.", "parameters": [ { "name": "userSettings", "in": "body", "schema": { "$ref": "#/definitions/UserSettings" }, "required": true, "x-example": { "defaultTimeRangeType": "DEFAULT", "appearance": "SYSTEM", "timezone": "LOCAL", "timeSeriesHoverTooltipConcise": true, "chartHoverTooltipMode": "VERBOSE", "defaultNumberFormats": { "data": { "sigFigs": 1, "displayOption": "SCIENTIFIC", "fixedDecimalPlaces": 1, "decimalPlaces": { "type": "fixed", "fixed": { "places": 1 } } } }, "relativeTimestampFormat": { "type": "temporalSubunits", "temporalSubunits": {} }, "vimModeEnabled": true, "defaultWorkbookVisibleInSearch": true } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UserSettings" }, "x-example": { "defaultTimeRangeType": "DEFAULT", "appearance": "SYSTEM", "timezone": "LOCAL", "timeSeriesHoverTooltipConcise": true, "chartHoverTooltipMode": "VERBOSE", "defaultNumberFormats": { "data": { "sigFigs": 1, "displayOption": "SCIENTIFIC", "fixedDecimalPlaces": 1, "decimalPlaces": { "type": "fixed", "fixed": { "places": 1 } } } }, "relativeTimestampFormat": { "type": "temporalSubunits", "temporalSubunits": {} }, "vimModeEnabled": true, "defaultWorkbookVisibleInSearch": true } } } } }, "/authentication/v2/org/settings": { "get": { "operationId": "AuthenticationServiceV2_getMyOrgSettings", "summary": "Get my org settings", "tags": [ "Authentication Service" ], "description": "Gets the settings of the org of the authenticated user.", "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/OrgSettings" }, "x-example": { "defaultTimeRangeType": "DEFAULT", "defaultWorkbookVisibleInSearch": true } } } }, "put": { "operationId": "AuthenticationServiceV2_updateMyOrgSettings", "summary": "Update my org settings", "tags": [ "Authentication Service" ], "description": "Updates the settings of the org of the authenticated user.", "parameters": [ { "name": "orgSettings", "in": "body", "schema": { "$ref": "#/definitions/OrgSettings" }, "required": true, "x-example": { "defaultTimeRangeType": "DEFAULT", "defaultWorkbookVisibleInSearch": true } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/OrgSettings" }, "x-example": { "defaultTimeRangeType": "DEFAULT", "defaultWorkbookVisibleInSearch": true } } } } }, "/authentication/v2/users": { "post": { "operationId": "AuthenticationServiceV2_searchUsersV2", "summary": "Search users v2", "tags": [ "Authentication Service" ], "description": "Searches for users by email and displayName.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/SearchUsersRequest" }, "required": true, "x-example": { "query": { "type": "and", "and": [] } } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/SearchUsersResponseV2" }, "x-example": { "results": [ { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } ], "nextPageToken": "" } } } } }, "/authentication/v2/users/batch": { "post": { "operationId": "AuthenticationServiceV2_getUsers", "summary": "Get users", "tags": [ "Authentication Service" ], "description": "Get users by RID. Returns objects for any of the requested RIDs that are members or guests of the caller's org.", "parameters": [ { "name": "userRids", "in": "body", "schema": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "UserRid" }, "uniqueItems": true, "example": [ "" ] }, "required": false, "description": "The RIDs of the users to get", "x-example": [ "" ] } ], "responses": { "200": { "description": "A successful response.", "schema": { "type": "array", "items": { "$ref": "#/definitions/UserV2" }, "uniqueItems": true }, "x-example": [ { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } ] } } } }, "/authentication/v2/users/{userRid}": { "get": { "operationId": "AuthenticationServiceV2_getUser", "summary": "Get user", "tags": [ "Authentication Service" ], "description": "Gets a user by RID. Throws if the requested RID is not a member or guest of the caller's org.", "parameters": [ { "name": "userRid", "in": "path", "type": "string", "format": "rid", "x-alias": "UserRid", "required": true } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/UserV2" }, "x-example": { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } } } } }, "/authentication/v2/jwks": { "get": { "operationId": "AuthenticationServiceV2_getJwks", "summary": "Get jwks", "tags": [ "Authentication Service" ], "description": "Returns JWKS (JSON Web Key Set) for MediaMTX JWT verification. Only available if MediaMTX integration is enabled.", "security": [], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/Jwks" }, "x-example": { "keys": [ { "kty": "", "kid": "", "use": "", "alg": "", "n": "", "e": "" } ] } } } } }, "/authentication/v2/batch-preregister-users": { "post": { "operationId": "AuthenticationServiceV2_batchPreregisterUsers", "summary": "Batch preregister users", "tags": [ "Authentication Service" ], "description": "Batch preregister users in the caller's organization. Only creates new users for emails that don't already exist — existing accounts are silently skipped and not returned in the response. The caller must be an admin of the organization.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/BatchPreregisterUsersRequest" }, "required": true, "x-example": { "emails": [ "" ] } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/BatchPreregisterUsersResponse" }, "x-example": { "users": { "": { "rid": "", "orgRid": "", "email": "", "displayName": "", "avatarUrl": "", "createdAt": "2026-01-01T00:00:00Z" } } } } } } }, "/authentication/v2/admin/org/login-activity": { "post": { "operationId": "AuthenticationServiceV2_listOrgLoginActivity", "summary": "List org login activity", "tags": [ "Authentication Service" ], "description": "Lists members of one or more orgs together with their most recent login into each org, sorted and paginated. The caller must be an admin of every org requested — defaults to the caller's own org if none are specified.", "parameters": [ { "name": "request", "in": "body", "schema": { "$ref": "#/definitions/ListOrgLoginActivityRequest" }, "required": true, "x-example": { "orgs": [ "" ], "isDescending": true, "nextPageToken": "", "pageSize": 1 } } ], "responses": { "200": { "description": "A successful response.", "schema": { "$ref": "#/definitions/ListOrgLoginActivityResponse" }, "x-example": { "results": [ { "userRid": "", "orgRid": "", "lastLoginAt": "2026-01-01T00:00:00Z" } ], "nextPageToken": "" } } } } }, "/authentication/v2/admin/users/{userRid}/deactivate": { "post": { "operationId": "AuthenticationServiceV2_deactivateUser", "summary": "Deactivate user", "tags": [ "Authentication Service" ], "description": "Deactivates a user in the caller's organization, preventing them from obtaining new Nominal session tokens in that org. Also revokes all of the user's API keys in the caller's organization. Caller must be an admin of their org. Target user must be a member or guest of the org.", "parameters": [ { "name": "userRid", "in": "path", "type": "string", "format": "rid", "x-alias": "UserRid", "required": true } ], "responses": { "204": { "description": "No content." } } } }, "/authentication/v2/admin/users/{userRid}/reactivate": { "post": { "operationId": "AuthenticationServiceV2_reactivateUser", "summary": "Reactivate user", "tags": [ "Authentication Service" ], "description": "Reactivates a user in the caller's organization. Caller must be an admin of their org. Target user must be a member or guest of the org.", "parameters": [ { "name": "userRid", "in": "path", "type": "string", "format": "rid", "x-alias": "UserRid", "required": true } ], "responses": { "204": { "description": "No content." } } } } }, "definitions": { "AppearanceSetting": { "type": "string", "enum": [ "SYSTEM", "LIGHT", "DARK" ] }, "BatchPreregisterUsersRequest": { "description": "Request to batch preregister users in the caller's organization. Only creates new users for emails that don't already exist. Newly created users are stored with an email claim matching their email address. Maximum of 1000 emails per request.", "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" }, "description": "The list of email addresses to preregister. Maximum 1000 entries." } }, "example": { "emails": [ "" ] } }, "BatchPreregisterUsersResponse": { "description": "Response containing only the newly created users keyed by email. Emails that already had existing accounts are silently skipped.", "type": "object", "properties": { "users": { "type": "object", "additionalProperties": { "$ref": "#/definitions/UserV2" }, "description": "Map of email to UserV2 for each newly created user." } } }, "ChartTooltipModeSetting": { "description": "Tooltip modes which affect the data displayed in chart tooltips, primarily for time series charts. VERBOSE: Shows all the chart's plotted series in the hover tooltip. CONCISE: Shows only the plotted series within the row currently being hovered. MULTI_ROW_CONCISE: Show separate tooltips for each row, where each shows the series plotted in that row. SINGLE: Shows only the plotted series closest to/under the cursor. NONE: Hides the tooltip entirely (also affects tooltips for other chart types).", "type": "string", "enum": [ "VERBOSE", "CONCISE", "MULTI_ROW_CONCISE", "SINGLE", "NONE" ] }, "DefaultNumberFormatConfigurations": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/definitions/NumberFormat" } ], "description": "Default number format for data values, e.g. chart tooltip and value table cell values." } } }, "DefaultTimeRangeTypeSetting": { "type": "string", "enum": [ "DEFAULT", "ABSOLUTE", "RELATIVE" ] }, "Jwk": { "description": "A JSON Web Key (JWK) representation for RSA public keys", "type": "object", "properties": { "kty": { "type": "string" }, "kid": { "type": "string" }, "use": { "type": "string" }, "alg": { "type": "string" }, "n": { "type": "string" }, "e": { "type": "string" } }, "required": [ "kty", "kid", "use", "alg", "n", "e" ] }, "Jwks": { "description": "A JSON Web Key Set (JWKS) containing one or more keys", "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/definitions/Jwk" } } } }, "ListOrgLoginActivityRequest": { "description": "Lists members of one or more orgs together with their most recent login into each org. The caller must be an admin of every org requested. Defaults to the caller's own org.", "type": "object", "properties": { "orgs": { "type": "array", "items": { "type": "string", "format": "rid", "x-alias": "OrgRid" }, "uniqueItems": true, "description": "Defaults to the caller's own org. The caller must be an admin of every org listed." }, "isDescending": { "type": "boolean", "description": "Sorts by last login time. Defaults to true (most recent login first, with users who have never logged in last). Set to false to sort oldest-first, with users who have never logged in first." }, "nextPageToken": { "type": "string", "x-alias": "Token" }, "pageSize": { "type": "integer", "format": "int32", "description": "Defaults to 100. Will throw if larger than 1_000." } }, "example": { "orgs": [ "" ], "isDescending": true, "nextPageToken": "", "pageSize": 1 } }, "ListOrgLoginActivityResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/OrgUserLoginActivity" } }, "nextPageToken": { "type": "string", "x-alias": "Token" } } }, "OrgSettings": { "type": "object", "properties": { "defaultTimeRangeType": { "$ref": "#/definitions/DefaultTimeRangeTypeSetting" }, "defaultWorkbookVisibleInSearch": { "type": "boolean", "description": "Whether newly created workbooks are visible in search by default." } } }, "OrgUserLoginActivity": { "type": "object", "properties": { "userRid": { "type": "string", "format": "rid", "x-alias": "UserRid" }, "orgRid": { "type": "string", "format": "rid", "x-alias": "OrgRid" }, "lastLoginAt": { "type": "string", "format": "date-time", "description": "The most recent time this user logged into orgRid. Absent if they have never logged in." } }, "required": [ "userRid", "orgRid" ] }, "SearchUsersQuery": { "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "and", "or", "exactMatch", "searchText" ] }, "and": { "type": "array", "items": { "$ref": "#/definitions/SearchUsersQuery" } }, "or": { "type": "array", "items": { "$ref": "#/definitions/SearchUsersQuery" } }, "exactMatch": { "type": "string", "description": "Performs case insensitive exact match on email" }, "searchText": { "type": "string", "description": "Searches email and display name" } }, "required": [ "type" ], "description": "Set `type` to the name of one of the other fields, and set only that field.", "example": { "type": "and", "and": [] } }, "SearchUsersRequest": { "type": "object", "properties": { "query": { "$ref": "#/definitions/SearchUsersQuery" }, "sortBy": { "allOf": [ { "$ref": "#/definitions/SortBy" } ], "description": "UPDATED_AT descending by default" }, "nextPageToken": { "type": "string", "x-alias": "Token" }, "pageSize": { "type": "integer", "format": "int32", "description": "Defaults to 100. Will throw if larger than 1_000." } }, "required": [ "query" ], "example": { "query": { "type": "and", "and": [] } } }, "SearchUsersResponseV2": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/UserV2" } }, "nextPageToken": { "type": "string", "x-alias": "Token" } } }, "SortBy": { "type": "object", "properties": { "isDescending": { "type": "boolean" }, "field": { "$ref": "#/definitions/SortByField" } }, "required": [ "isDescending", "field" ] }, "SortByField": { "type": "string", "enum": [ "NAME", "EMAIL", "CREATED_AT", "UPDATED_AT" ] }, "TimezoneSetting": { "type": "string", "enum": [ "LOCAL", "UTC" ] }, "UpdateMyProfileRequest": { "type": "object", "properties": { "displayName": { "type": "string" } }, "required": [ "displayName" ], "example": { "displayName": "" } }, "UserSettings": { "type": "object", "properties": { "defaultTimeRangeType": { "$ref": "#/definitions/DefaultTimeRangeTypeSetting" }, "appearance": { "$ref": "#/definitions/AppearanceSetting" }, "timezone": { "$ref": "#/definitions/TimezoneSetting" }, "timeSeriesHoverTooltipConcise": { "type": "boolean", "x-deprecated": "Use `chartHoverTooltipMode` instead. If `chartHoverTooltipMode` is not set, this field will be used: `true` as `SINGLE` and `false` as `VERBOSE`." }, "chartHoverTooltipMode": { "$ref": "#/definitions/ChartTooltipModeSetting" }, "defaultNumberFormats": { "$ref": "#/definitions/DefaultNumberFormatConfigurations" }, "relativeTimestampFormat": { "allOf": [ { "$ref": "#/definitions/RelativeTimestampFormat" } ], "description": "Relative timestamp display preference." }, "vimModeEnabled": { "type": "boolean" }, "defaultWorkbookVisibleInSearch": { "type": "boolean", "description": "Whether newly created workbooks are visible in search by default. If absent, the organization default applies." } } }, "UserV2": { "type": "object", "properties": { "rid": { "type": "string", "format": "rid", "x-alias": "UserRid" }, "orgRid": { "type": "string", "format": "rid", "x-alias": "OrgRid" }, "email": { "type": "string" }, "displayName": { "type": "string" }, "avatarUrl": { "type": "string", "description": "Avatar URL or a default avatar if the user does not have one." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "rid", "orgRid", "email", "displayName", "avatarUrl" ] }, "DecimalPlaces": { "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "fixed", "max" ] }, "fixed": { "$ref": "#/definitions/FixedDecimalPlaces" }, "max": { "$ref": "#/definitions/MaxDecimalPlaces" } }, "required": [ "type" ], "description": "Set `type` to the name of one of the other fields, and set only that field.", "example": { "type": "fixed", "fixed": { "places": 1 } } }, "FixedDecimalPlaces": { "description": "Format the number to a fixed number of decimal places, padding with zeroes or rounding as needed.", "type": "object", "properties": { "places": { "type": "integer", "format": "int32" } }, "required": [ "places" ] }, "MaxDecimalPlaces": { "description": "Format the number to a maximum number of decimal places, rounding numbers that have greater precision.", "type": "object", "properties": { "places": { "type": "integer", "format": "int32" } }, "required": [ "places" ] }, "NumberFormat": { "description": "Number format for numeric cells, eg 1e4 | 10000 | 10,000.", "type": "object", "properties": { "sigFigs": { "type": "integer", "format": "int32", "description": "Include the specified number of significant figures, rounding if needed." }, "displayOption": { "allOf": [ { "$ref": "#/definitions/NumberFormatDisplayOption" } ], "description": "The base display format for the number." }, "fixedDecimalPlaces": { "type": "integer", "format": "int32", "x-deprecated": "use decimalPlaces instead" }, "decimalPlaces": { "allOf": [ { "$ref": "#/definitions/DecimalPlaces" } ], "description": "Options for formatting the decimal part of number." } } }, "NumberFormatDisplayOption": { "type": "string", "enum": [ "SCIENTIFIC", "SUCCINCT", "LOCALE", "PLAIN" ] }, "RelativeTimestampFormat": { "description": "User-level display format for relative timestamps.\n\nSet `type` to the name of one of the other fields, and set only that field.", "type": "object", "x-union": true, "properties": { "type": { "type": "string", "enum": [ "temporalSubunits", "totalSeconds" ] }, "temporalSubunits": { "$ref": "#/definitions/TemporalSubunitsRelativeTimestampFormat" }, "totalSeconds": { "$ref": "#/definitions/TotalSecondsRelativeTimestampFormat" } }, "required": [ "type" ], "example": { "type": "temporalSubunits", "temporalSubunits": {} } }, "TemporalSubunitsRelativeTimestampFormat": { "description": "Display relative timestamps as temporal subunits, such as 1h 20m 30s.", "type": "object", "properties": {} }, "TotalSecondsRelativeTimestampFormat": { "description": "Display relative timestamps as a total number of seconds.", "type": "object", "properties": {} } }, "tags": [ { "name": "Authentication Service", "x-displayName": "Authentication service", "description": "This service provides operations for managing user and org profiles/settings. Its name is a bit of a misnomer.", "x-errors": [ { "status": 403, "errorCode": "PERMISSION_DENIED", "errorName": "Authentication:NotAuthorized" }, { "status": 404, "errorCode": "NOT_FOUND", "errorName": "Authentication:UserNotFound" }, { "status": 404, "errorCode": "NOT_FOUND", "errorName": "Authentication:OrgNotFound" }, { "status": 500, "errorCode": "FAILED_PRECONDITION", "errorName": "Authentication:MultipleUsersForSameEmail" }, { "status": 403, "errorCode": "PERMISSION_DENIED", "errorName": "Authentication:NotAuthorizedAdmin" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Authentication:SearchUsersLimitExceeded" }, { "status": 400, "errorCode": "INVALID_ARGUMENT", "errorName": "Authentication:OrgLoginActivityLimitExceeded" } ] } ] }