{"openapi":"3.0.1","info":{"title":"Users","description":"Temporary V4 Users API exposing V4 user routes while the WorkOS-backed user-management surface is being tested.","version":"v4"},"servers":[{"url":"https://talk.perspio.io/users/v4","description":"AU Region"},{"url":"https://us-talk.perspio.io/users/v4","description":"US Region"}],"paths":{"/":{"get":{"tags":["Users"],"summary":"List Users","description":"Fetch a paged list of users from the V4 user-management service.","operationId":"listUsersV4","parameters":[{"name":"search","in":"query","description":"Search term","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of records to return","schema":{"minimum":1,"type":"integer","format":"int32"}},{"name":"continuationToken","in":"query","description":"Continuation token from a previous page","schema":{"type":"string"}},{"name":"status","in":"query","description":"Status filter","schema":{"type":"string"}},{"name":"userType","in":"query","description":"User type filter","schema":{"type":"string"}},{"name":"homeRegion","in":"query","description":"Home region filter","schema":{"type":"string"}},{"name":"accessProfileId","in":"query","description":"Access profile id filter","schema":{"type":"string"}},{"name":"isPerspioStaff","in":"query","description":"Perspio staff filter","schema":{"type":"boolean"}},{"name":"hasUnrestrictedAccess","in":"query","description":"Unrestricted access filter","schema":{"type":"boolean"}},{"name":"select","in":"query","description":"Comma-separated fields to include in the user response","schema":{"type":"string"}},{"name":"includeRemoved","in":"query","description":"Include removed users in the result.","schema":{"type":"boolean"}},{"name":"fields","in":"query","description":"Alias for select - comma-separated list of fields to return.","schema":{"type":"string"}},{"name":"$select","in":"query","description":"Alias for select (OData style).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPage"},"example":{"result":[],"resultCount":0,"totalCount":0,"continuationToken":null}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/{principalId}":{"get":{"tags":["Users"],"summary":"Get User","description":"Fetch a user by principal id.","operationId":"getUserV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"select","in":"query","description":"Comma-separated fields to include in the user response","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Alias for select.","schema":{"type":"string"}},{"name":"$select","in":"query","description":"Alias for select (OData style).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"patch":{"tags":["Users"],"summary":"Update User","description":"Patch supported user profile fields by principal id.","operationId":"updateUserV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"example":[{"op":"add","path":"string","value":{},"oldValue":{}}]}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"delete":{"tags":["Users"],"summary":"Delete User","description":"Remove a user by principal id.","operationId":"deleteUserV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The request was applied."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/signinlogs":{"get":{"tags":["Users"],"summary":"Get User Sign-In Logs","description":"Fetch WorkOS-backed sign-in logs for a user within a maximum 30-day date range.","operationId":"getUserSignInLogsV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Inclusive start timestamp for sign-in logs","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Inclusive end timestamp for sign-in logs","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SignInLog"}},"example":[{"userPrincipalName":"jane.doe@perspio.io","userId":"U-1","signInDate":"2026-06-29T10:00:00.0000000+00:00","appName":"Perspio Web","conditionalAccessStatus":"success","isInteractive":true,"status":"success"}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/enable":{"post":{"tags":["Users"],"summary":"Enable User","description":"Enable a user's organization membership.","operationId":"enableUserV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/disable":{"post":{"tags":["Users"],"summary":"Disable User","description":"Disable a user's organization membership.","operationId":"disableUserV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/preferences":{"get":{"tags":["Users"],"summary":"Get User Preferences","description":"Fetch preferences for a user by principal id.","operationId":"getUserPreferencesV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"patch":{"tags":["Users"],"summary":"Update User Preferences","description":"Patch preferences for a user by principal id.","operationId":"updateUserPreferencesV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"example":[{"op":"add","path":"string","value":{},"oldValue":{}}]}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPreferences"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/access":{"get":{"tags":["Users"],"summary":"Get User Access","description":"Fetch a user's access assignment by principal id.","operationId":"getUserAccessV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAccess"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","accessProfileId":"AP-001","hasUnrestrictedAccess":false,"permissions":["assets.read"],"securityGroups":[{"id":"SG-1","name":"Fleet"}],"modules":[],"updatedAt":"2026-06-20T12:00:00.0000000+00:00","accessSource":"profile","editable":true,"sources":[],"allowedActions":["assets.read"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"put":{"tags":["Users"],"summary":"Replace User Access","description":"Replace a user's access assignment by principal id.","operationId":"replaceUserAccessV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessUpdate"},"example":{"accessProfileId":"string","permissions":["string"],"securityGroups":["string"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAccess"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","accessProfileId":"AP-001","hasUnrestrictedAccess":false,"permissions":["assets.read"],"securityGroups":[{"id":"SG-1","name":"Fleet"}],"modules":[],"updatedAt":"2026-06-20T12:00:00.0000000+00:00","accessSource":"profile","editable":true,"sources":[],"allowedActions":["assets.read"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/currentUser":{"get":{"tags":["CurrentUser"],"summary":"Get Current User","description":"Fetch the authenticated user.","operationId":"getCurrentUserV4","parameters":[{"name":"select","in":"query","description":"Comma-separated fields to include in the user response","schema":{"type":"string"}},{"name":"fields","in":"query","description":"Alias for select.","schema":{"type":"string"}},{"name":"$select","in":"query","description":"Alias for select (OData style).","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"patch":{"tags":["CurrentUser"],"summary":"Update Current User","description":"Patch supported fields for the authenticated user.","operationId":"updateCurrentUserV4","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"example":[{"op":"add","path":"string","value":{},"oldValue":{}}]}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/currentUser/preferences":{"get":{"tags":["CurrentUser"],"summary":"Get Current User Preferences","description":"Fetch preferences for the authenticated user.","operationId":"getCurrentUserPreferencesV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserPreferences"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00","resolvedLocalisationPreferences":{"timeZone":"Australia/Sydney","units":"metric"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}},"patch":{"tags":["CurrentUser"],"summary":"Update Current User Preferences","description":"Patch preferences for the authenticated user.","operationId":"updateCurrentUserPreferencesV4","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"example":[{"op":"add","path":"string","value":{},"oldValue":{}}]}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUserPreferences"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00","resolvedLocalisationPreferences":{"timeZone":"Australia/Sydney","units":"metric"}}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/currentUser/access":{"get":{"tags":["CurrentUser"],"summary":"Get Current User Access","description":"Fetch the authenticated user's access assignment.","operationId":"getCurrentUserAccessV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAccess"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","accessProfileId":"AP-001","hasUnrestrictedAccess":false,"permissions":["assets.read"],"securityGroups":[{"id":"SG-1","name":"Fleet"}],"modules":[],"updatedAt":"2026-06-20T12:00:00.0000000+00:00","accessSource":"profile","editable":true,"sources":[],"allowedActions":["assets.read"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}},"patch":{"tags":["CurrentUser"],"summary":"Update Current User Access","description":"Patch the authenticated user's access assignment.","operationId":"updateCurrentUserAccessV4","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessUpdate"},"example":{"accessProfileId":"string","permissions":["string"],"securityGroups":["string"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserAccess"},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","accessProfileId":"AP-001","hasUnrestrictedAccess":false,"permissions":["assets.read"],"securityGroups":[{"id":"SG-1","name":"Fleet"}],"modules":[],"updatedAt":"2026-06-20T12:00:00.0000000+00:00","accessSource":"profile","editable":true,"sources":[],"allowedActions":["assets.read"]}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}},"/currentUser/logs/recent":{"get":{"tags":["CurrentUser"],"summary":"Get Current User Logs","description":"Retrieve recent activity logs for the authenticated user.","operationId":"getCurrentUserLogsV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"dateUtc":{"type":"string","description":"UTC timestamp of the activity."},"method":{"type":"string","description":"HTTP method."},"url":{"type":"string","description":"Request URL."},"responseCode":{"type":"integer","description":"HTTP response status code."}}}},"example":[{"dateUtc":"2026-06-30T01:00:00.0000000+00:00","method":"GET","url":"/users","responseCode":200}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/currentUser/support/tickets":{"post":{"tags":["CurrentUser"],"summary":"Create Support Ticket","description":"Create a support ticket for the authenticated user.","operationId":"createSupportTicketV4","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"The request was applied.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Result message."},"ticketId":{"type":"string","description":"Id of the created support ticket."}}},"example":{"message":"Support ticket created.","ticketId":"TICK-00123"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/access/profiles":{"get":{"tags":["AccessProfiles"],"summary":"Get User Access Profiles","description":"List the available role/access profiles.","operationId":"getRoleDefinitionProfilesV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Access profile id."},"name":{"type":"string","description":"Profile name."},"profile":{"type":"string","description":"Profile key."},"modules":{"type":"array","items":{"type":"object"},"description":"Modules included in the profile."},"readWrite":{"type":"boolean","description":"Whether the profile grants read-write access."}}}},"example":[{"id":"AP-001","name":"Fleet Viewer","profile":"fleet.viewer","modules":[],"readWrite":false}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/userstask":{"post":{"tags":["Users"],"summary":"Create User Job","description":"Create a background task for user creation using the legacy user-task backend.","operationId":"createUserJobV4","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"The request was applied.","content":{"application/json":{"schema":{"type":"object"},"example":{"statusUrl":"https://api/jobs/JOB-001/status"}}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/logs":{"get":{"tags":["UserLogs"],"summary":"Get User Logs","description":"Retrieve user audit logs.","operationId":"getUserLogsV4","parameters":[{"name":"from","in":"query","description":"Start time in ISO 8601 format","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End time in ISO 8601 format","schema":{"type":"string","format":"date-time"}},{"name":"page_size","in":"query","description":"Page size to return per page","schema":{"type":"integer","format":"int32"}},{"name":"source","in":"query","description":"Audit log source","schema":{"type":"string"}},{"name":"objectid","in":"query","description":"Object id filter","schema":{"type":"string"}},{"name":"backendName","in":"query","description":"Filter by backend function name.","schema":{"type":"string"}},{"name":"orderBy","in":"query","description":"Field to order the results by.","schema":{"type":"string"}},{"name":"url","in":"query","description":"Filter by request URL.","schema":{"type":"string"}},{"name":"useremail","in":"query","description":"Filter by user email.","schema":{"type":"string"}},{"name":"userid","in":"query","description":"Filter by user id.","schema":{"type":"string"}},{"name":"ContinuationToken","in":"header","description":"Opaque token from a previous response's ContinuationToken header, to fetch the next page.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","headers":{"ContinuationToken":{"description":"Opaque token to fetch the next page; absent on the last page.","schema":{"type":"string"},"example":"eyJ0b2tlbiI6IjEyMyJ9"},"ResultCount":{"description":"Number of items in this page.","schema":{"type":"integer"},"example":50},"TotalCount":{"description":"Total across all pages.","schema":{"type":"integer"},"example":1234}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of the log entry."},"dateUtc":{"type":"string","description":"UTC timestamp of the request."},"correlationId":{"type":"string","description":"Correlation id."},"tenantId":{"type":"string","description":"Tenant id."},"objectId":{"type":"string","description":"Id of the object acted upon."},"durationMilliseconds":{"type":"integer","description":"Request duration in milliseconds."},"method":{"type":"string","description":"HTTP method."},"url":{"type":"string","description":"Request URL."},"responseCode":{"type":"integer","description":"HTTP response status code."},"backendName":{"type":"string","description":"Backend function name."},"userName":{"type":"string","description":"Display name of the user."},"userId":{"type":"string","description":"Id of the user."},"userEmail":{"type":"string","description":"Email of the user."},"userIpAddress":{"type":"string","description":"IP address of the user."}}}},"example":[{"id":"L-001","dateUtc":"2026-06-30T01:00:00.0000000+00:00","method":"GET","url":"/users","responseCode":200,"userId":"U-1"}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}},"post":{"tags":["UserLogs"],"summary":"Create User Log","description":"Write a user audit log entry.","operationId":"createUserLogV4","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"The audit log entry was written."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/preferences":{"get":{"tags":["Users"],"summary":"Get Users Preferences","description":"Fetch preferences for all non-staff users from the V4 user-management service.","operationId":"getUsersPreferencesV4","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UserPreferences"}},"example":[{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard"}]}}},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"500":{"description":"Internal Server Error"}}}},"/{principalId}/resendwelcomeemail":{"post":{"tags":["Users"],"summary":"Resend Welcome Email","description":"Reset the user's linked Entra password and send a welcome email.","operationId":"resendWelcomeEmailV4","parameters":[{"name":"principalId","in":"path","description":"User principal id","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The request was applied."},"400":{"description":"Bad Request"},"401":{"description":"Unauthorized"},"404":{"description":"Not Found"},"500":{"description":"Internal Server Error"}}}}},"components":{"schemas":{"UserPage":{"type":"object","properties":{"result":{"type":"array","items":{"$ref":"#/components/schemas/User"},"description":"The page of results."},"resultCount":{"type":"integer","description":"Number of items in this page.","format":"int32"},"totalCount":{"type":"integer","description":"Total number of items across all pages.","format":"int32"},"continuationToken":{"type":"string","description":"Token to fetch the next page; absent on the last page.","nullable":true}},"example":{"result":[],"resultCount":0,"totalCount":0,"continuationToken":null}},"GroupPage":{"type":"object","properties":{"result":{"type":"array","items":{"$ref":"#/components/schemas/Group"},"description":"The page of results."},"resultCount":{"type":"integer","description":"Number of items in this page.","format":"int32"},"totalCount":{"type":"integer","description":"Total number of items across all pages.","format":"int32"},"continuationToken":{"type":"string","description":"Token to fetch the next page; absent on the last page.","nullable":true}}},"User":{"type":"object","properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"status":{"type":"string","description":"Status of the user."},"upn":{"type":"string","description":"User principal name.","nullable":true},"email":{"type":"string","description":"Email address.","format":"email","nullable":true},"displayName":{"type":"string","description":"Display name.","nullable":true},"givenName":{"type":"string","description":"Given name.","nullable":true},"surname":{"type":"string","description":"Surname.","nullable":true},"userType":{"type":"string","description":"Type of user.","nullable":true},"isPerspioStaff":{"type":"boolean","description":"Whether the user is Perspio staff."},"accessProfileId":{"type":"string","description":"Id of the access profile assigned to the user.","nullable":true},"hasUnrestrictedAccess":{"type":"boolean","description":"Whether the user has unrestricted data access."},"mobile":{"type":"string","description":"Mobile number.","nullable":true},"homeRegion":{"type":"string","description":"Home region of the user.","nullable":true},"companyName":{"type":"string","description":"Company name.","nullable":true},"streetAddress1":{"type":"string","nullable":true},"streetAddress2":{"type":"string","nullable":true},"postCode":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"avatarUrl":{"type":"string","description":"URL of the user's avatar.","nullable":true},"lastLoginAt":{"type":"string","description":"UTC timestamp of the last login.","format":"date-time","nullable":true},"eulaAccepted":{"type":"boolean","description":"Whether the EULA has been accepted."},"eulaVersion":{"type":"string","nullable":true},"eulaAcceptedDate":{"type":"string","format":"date-time","nullable":true}},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","status":"active","upn":"jane.doe@perspio.io","email":"jane.doe@example.com","displayName":"Jane Doe","givenName":"Jane","surname":"Doe","userType":"standard","isPerspioStaff":false,"accessProfileId":"AP-001","hasUnrestrictedAccess":false,"mobile":"+61400000000","homeRegion":"au","companyName":"Acme","avatarUrl":null,"lastLoginAt":"2026-06-29T10:00:00.0000000+00:00","eulaAccepted":true}},"UserPreferences":{"type":"object","properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"landingPage":{"type":"string","description":"Default landing page.","nullable":true},"assetFilters":{"type":"string","description":"Saved asset filters.","nullable":true},"assetColumns":{"type":"string","description":"Saved asset column configuration.","nullable":true},"assetMarkerProfiles":{"type":"string","description":"Saved asset marker profiles.","nullable":true},"localisationPreferences":{"type":"string","description":"Localisation preferences.","nullable":true},"updatedAt":{"type":"string","description":"UTC timestamp when the record was last updated.","format":"date-time","nullable":true}},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00"}},"LocalisationPreferences":{"type":"object","additionalProperties":{"type":"string"},"description":"Resolved localisation preferences keyed by preference name, for example timeZone, dateFormat, or unit categories.","nullable":true},"CurrentUserPreferences":{"type":"object","allOf":[{"$ref":"#/components/schemas/UserPreferences"},{"type":"object","properties":{"resolvedLocalisationPreferences":{"$ref":"#/components/schemas/LocalisationPreferences"}}}],"properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"landingPage":{"type":"string","description":"Default landing page.","nullable":true},"assetFilters":{"type":"string","description":"Saved asset filters.","nullable":true},"assetColumns":{"type":"string","description":"Saved asset column configuration.","nullable":true},"assetMarkerProfiles":{"type":"string","description":"Saved asset marker profiles.","nullable":true},"localisationPreferences":{"type":"string","description":"Localisation preferences.","nullable":true},"updatedAt":{"type":"string","description":"UTC timestamp when the record was last updated.","format":"date-time","nullable":true},"resolvedLocalisationPreferences":{"type":"object","additionalProperties":{"type":"string"},"description":"Resolved localisation preferences (effective values applied for the current user)."}},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","landingPage":"dashboard","assetFilters":"{}","assetColumns":"[]","assetMarkerProfiles":"[]","localisationPreferences":"{}","updatedAt":"2026-06-20T12:00:00.0000000+00:00","resolvedLocalisationPreferences":{"timeZone":"Australia/Sydney","units":"metric"}}},"UserAccess":{"type":"object","properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"accessProfileId":{"type":"string","description":"Id of the access profile assigned to the user.","nullable":true},"hasUnrestrictedAccess":{"type":"boolean","description":"Whether the user has unrestricted data access."},"permissions":{"type":"array","items":{"type":"string"},"description":"Permissions granted to the user."},"securityGroups":{"type":"array","items":{"$ref":"#/components/schemas/SecurityGroupSummary"},"description":"Security groups the user belongs to."},"modules":{"type":"array","items":{"type":"object"},"description":"Modules the user can access."},"updatedAt":{"type":"string","description":"UTC timestamp when the record was last updated.","format":"date-time"},"accessSource":{"type":"string","description":"Where the user's access is derived from."},"editable":{"type":"boolean","description":"Whether the access can be edited."},"sources":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"principalId":{"type":"string","description":"Unique principal id of the user."},"name":{"type":"string","description":"Display name."}}},"description":"Principal access sources contributing to this access."},"allowedActions":{"type":"array","items":{"type":"string"},"description":"Actions the user is allowed to perform."}},"example":{"principalId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","accessProfileId":"AP-001","hasUnrestrictedAccess":false,"permissions":["assets.read"],"securityGroups":[{"id":"SG-1","name":"Fleet"}],"modules":[],"updatedAt":"2026-06-20T12:00:00.0000000+00:00","accessSource":"profile","editable":true,"sources":[],"allowedActions":["assets.read"]}},"SecurityGroupSummary":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier."},"name":{"type":"string","description":"Display name."}}},"Group":{"type":"object","properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"principalTenantId":{"type":"string","format":"uuid","nullable":true},"tenantId":{"type":"string"},"ownerTenantId":{"type":"string"},"name":{"type":"string","description":"Display name."},"description":{"type":"string","nullable":true},"status":{"type":"string","description":"Status of the user."},"accessProfileId":{"type":"string","description":"Id of the access profile assigned to the user.","nullable":true},"hasUnrestrictedAccess":{"type":"boolean","description":"Whether the user has unrestricted data access."},"memberCount":{"type":"integer","format":"int32"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","description":"UTC timestamp when the record was last updated.","format":"date-time"}}},"GroupMember":{"type":"object","properties":{"principalId":{"type":"string","description":"Unique principal id of the user.","format":"uuid"},"status":{"type":"string","description":"Status of the user."},"email":{"type":"string","description":"Email address.","format":"email","nullable":true},"upn":{"type":"string","description":"User principal name.","nullable":true},"displayName":{"type":"string","description":"Display name.","nullable":true},"givenName":{"type":"string","description":"Given name.","nullable":true},"surname":{"type":"string","description":"Surname.","nullable":true}}},"SignInLog":{"type":"object","properties":{"userPrincipalName":{"type":"string","description":"User principal name.","nullable":true},"userId":{"type":"string","description":"User id.","nullable":true},"signInDate":{"type":"string","description":"UTC timestamp of the sign-in.","format":"date-time","nullable":true},"appName":{"type":"string","description":"Application used to sign in.","nullable":true},"conditionalAccessStatus":{"type":"string","description":"Conditional access status.","nullable":true},"isInteractive":{"type":"boolean","description":"Whether the sign-in was interactive.","nullable":true},"status":{"type":"string","description":"Status of the user.","nullable":true}},"example":{"userPrincipalName":"jane.doe@perspio.io","userId":"U-1","signInDate":"2026-06-29T10:00:00.0000000+00:00","appName":"Perspio Web","conditionalAccessStatus":"success","isInteractive":true,"status":"success"}},"JsonPatchOperation":{"required":["op","path"],"type":"object","properties":{"op":{"enum":["add","remove","replace"],"type":"string"},"path":{"type":"string"},"value":{"nullable":true},"oldValue":{"nullable":true}}},"AccessUpdate":{"type":"object","properties":{"accessProfileId":{"type":"string","description":"Id of the access profile assigned to the user.","nullable":true},"permissions":{"type":"array","items":{"type":"string"},"description":"Permissions granted to the user.","nullable":true},"securityGroups":{"type":"array","items":{"type":"string"},"description":"Security groups the user belongs to.","nullable":true}}},"GroupUpdate":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"Display name."},"description":{"type":"string","nullable":true}}},"GroupMembersUpdate":{"required":["principalIds"],"type":"object","properties":{"principalIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid"}}}}},"securitySchemes":{"oauth2":{"type":"oauth2","description":"Client credentials from your Perspio API application. See Get Access Token.","flows":{"clientCredentials":{"tokenUrl":"/auth/v3/token","scopes":{}}}},"subscriptionKey":{"type":"apiKey","name":"Ocp-Apim-Subscription-Key","in":"header","description":"Your tenant's subscription key, from your API application."},"tenantId":{"type":"apiKey","name":"tid","in":"header","description":"Your tenant ID (tid), from your API application."}}},"security":[{"oauth2":[],"subscriptionKey":[],"tenantId":[]}],"tags":[{"name":"Users"},{"name":"CurrentUser"},{"name":"AccessProfiles","description":"Role/access profiles."},{"name":"UserLogs","description":"User audit and activity logs."}],"x-readme":{"oauth-options":{"useInsecureClientAuthentication":true}}}