Docs/admin users permissions api

.gitignore

@@ -20,3 +20,4 @@ code-samples/**/obj/*
 *.sln
 .idea/
 *.iml
+engage-voice-api-docs.code-workspace

docs/authentication/auth-engage.md

@@ -25,6 +25,16 @@ Here is an example using cURL:
 
 In the response, you will see a very long string for an `accessToken`. You'll want to copy and save this for your next call.  You will also see a shorter string for a `refreshToken`. Save this token as well to [refresh your access token](#refresh-ringcentral-engage-access-token) when the access token expires.
 
+## Refresh RingCentral Engage Access Token
+
+Use the `refreshToken` returned by the Engage login response to renew the Engage access token when it expires.
+
+```http
+POST https://engage.ringcentral.com/api/auth/token/refresh?refresh_token={refreshToken}
+```
+
+The response returns a new `accessToken` and `refreshToken`. Save the new refresh token for the next refresh request.
+
 ## Generate a Permanent API Token
 
 In specific instances, a permanent API token is desired (for example, calling an API from the IVR). You can create permanent API tokens for this instance. Every time you run the method below, a new API token will be created and returned. You can also [retrieve a list](#list-all-personal-api-tokens) of permanent API tokens to see which tokens are still working.

docs/integration/admin.md

@@ -4,7 +4,7 @@ The following set of APIs are for admins that need to manage their sub accounts,
 
 ## User List
 
-The user list returns a list of admins on the account. For a list of agents, please use the [Agents](https://developers.ringcentral.com/engage/voice/api-reference/Integration-Agent-Controller/getAgentList) API. The [public user list](https://developers.ringcentral.com/engage/voice/api-reference/Users/listAllUsers) most developers will use has many details including creation date, enabled status, and roles. However, for integrations, a smaller set of user data may be all that is needed, but with the added ability to distinguish the RingCX user name from the RingEX user name and the environment ID. For this purpose, there's an [integration user list](https://developers.ringcentral.com/engage/voice/api-reference/Integration-User-Controller/getUserList) that can be used instead.
+The user list returns a list of admins on the account. For a list of agents, please use the [Agents](https://developers.ringcentral.com/engage/voice/api-reference/Integration-Agent-Controller/getAgentList) API. The [public user list](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/listAllUsers) most developers will use has many details including creation date, enabled status, and roles. However, for integrations, a smaller set of user data may be all that is needed, but with the added ability to distinguish the RingCX user name from the RingEX user name and the environment ID. For this purpose, there's an [integration user list](https://developers.ringcentral.com/engage/voice/api-reference/Integration-User-Controller/getUserList) that can be used instead.
 
 ## Sub-Accounts
 
@@ -16,7 +16,7 @@ Most developers will want a list of agents and agent groups, but for workforce m
 
 ## Queue Groups with Agents
 
-Once known as gates, queues are inbound routing rules for customers calling in to a number. Typically, queues have agents assigned to them and each queue would have to be iterated through to find all the agents assigned to a queue group. However, the [gate group with agents](https://developers.ringcentral.com/engage/voice/api-reference/Integration-Gate-Group-Controller/getGateGroupsWithAgents) integration API allows you to get a complete list of all queues in a queue group and the agents contained in that queue in a single call.
+Once known as gates, queues are inbound routing rules for customers calling in to a number. Typically, queues have agents assigned to them and each queue would have to be iterated through to find all the agents assigned to a queue group. However, the [gate group with agents](https://developers.ringcentral.com/engage/voice/api-reference/Public-Integration-API/getQueuesWithAgents) integration API allows you to get a complete list of all queues in a queue group and the agents contained in that queue in a single call.
 
 !!! info "This is not active agents in a queue"
     This API only returns a list of agents assigned to the queue. It does not return a list of agents actively receivng calls and chats from a queue.

docs/users/admin-users-and-permissions.md

@@ -0,0 +1,231 @@
+# Admin User and Permission APIs
+
+The Admin User and Permission APIs let you manage RingCX administrative users, role assignments, rights documents, API tokens, and account-level authentication checks. Use them when user and permission changes are driven by an external identity or governance process.
+
+## Strategic Overview
+
+Agents and administrators are related but not identical. Agent APIs manage contact-center users who handle interactions. Admin user and permission APIs manage access to the Admin portal and administrative API capabilities.
+
+### Key Use Cases
+
+* **User Governance:** List users and inspect effective permissions for audits.
+* **Role Automation:** Add or remove platform roles during onboarding and offboarding.
+* **Rights Document Management:** Create or update rights documents that define administrative access.
+* **Auth Utilities:** Validate tokens and support password reset workflows.
+
+### Required Permissions & Scopes
+
+#### 1. Configure OAuth Scopes
+
+Your application needs the `ReadAccounts` OAuth scope.
+
+#### 2. Enable RingCX Admin Access
+
+The authenticating user must have sufficient Admin portal permissions to read users and update roles or rights documents. User create/list operations require `MANAGE_USERS` or `SUPER_USER`; rights document assignment requires `MANAGE_RIGHTS` or `SUPER_USER`. Use least privilege for automation accounts, and separate read-only audit automation from onboarding/offboarding automation.
+
+!!! warning "Common Authorization Errors"
+    If the OAuth token is valid but the user cannot manage users, roles, or rights documents, the API returns an error similar to:
+    ```json
+    {
+      "errorCode": "access.denied.exception",
+      "generalMessage": "You do not have permission to access this resource",
+      "timestamp": 1611847650696
+    }
+    ```
+
+## Users
+
+| Operation | Method and Path | API Reference |
+| --- | --- | --- |
+| List users | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/listAllUsers) |
+| Create user | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/users` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/createUser) |
+| Get user | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getUser) |
+| Update user | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/updateUser) |
+| Set active state | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/setIsActive` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/setUserIsActive) |
+| Delete user | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/deleteUser) |
+
+Use `activeOnly=true` to list only enabled users and `flatten=true` when you need a flat list instead of a hierarchy.
+
+## Roles
+
+Roles are coarse-grained access assignments. Use role endpoints for straightforward role membership changes.
+
+| Operation | Method and Path | API Reference |
+| --- | --- | --- |
+| List user roles | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/roles` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getRoles) |
+| Add role | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/roles/{roleType}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/addRole) |
+| Remove role | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/roles/{roleType}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/removeRole) |
+
+## Rights Documents
+
+Rights documents provide detailed administrative permissions. Use these endpoints for advanced permission management or audit tooling.
+
+| Operation | Method and Path | API Reference |
+| --- | --- | --- |
+| List rights docs | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/rightsDocs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getRightsDocs) |
+| Create rights doc | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/rightsDocs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/createRightsDoc) |
+| Update rights doc | `PUT https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/rightsDocs/{rightsDocId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/updateRightsDoc) |
+| Delete rights doc | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/rightsDocs/{rightsDocId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/deleteRightsDoc) |
+| List assigned rights docs | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/assignedRightsDocs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getUsersAssignedRightsDocs2) |
+| List assigned master rights docs | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/assignedMasterRightsDocs` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getUsersAssignedRightsDocs) |
+| Assign rights doc | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/rightsDocs/{rightsDocId}/assignments` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/assignRightsDoc) |
+| Assign user to rights docs | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/rightsDocs/assignments/{userId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/assignUserToRightsDocs) |
+| Delete assignment | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/rightsDocs/{rightsDocId}/assignments/{assignedUserId}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/deleteRightsDocAssignment) |
+
+## API Tokens and Auth Utilities
+
+| Operation | Method and Path | API Reference |
+| --- | --- | --- |
+| List API tokens | `GET https://ringcx.ringcentral.com/voice/api/v1/admin/token` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/getApiTokensForLoggedInUser) |
+| Create API token | `POST https://ringcx.ringcentral.com/voice/api/v1/admin/token` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/createApiTokenForLoggedInUser) |
+| Remove API token | `DELETE https://ringcx.ringcentral.com/voice/api/v1/admin/token/{token}` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/removeApiToken) |
+| Validate token | `GET https://ringcx.ringcentral.com/voice/api/v1/auth/isTokenValid` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/isTokenValid) |
+| Reset password | `POST https://ringcx.ringcentral.com/voice/api/v1/auth/passwordReset` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/passwordReset) |
+| Request password reset | `POST https://ringcx.ringcentral.com/voice/api/v1/auth/passwordResetRequest` | [Reference](https://developers.ringcentral.com/engage/voice/api-reference/Admin-Users-and-Permissions/passwordResetRequest) |
+
+API tokens are long-lived authenticated-user tokens. Create and rotate them only for service accounts that are governed like other administrative users.
+
+## Recommended Workflow
+
+1. List or create the user.
+2. Apply required roles for broad access.
+3. Create or assign rights documents for detailed access.
+4. Verify effective access by reading assigned and aggregated rights documents.
+5. Remove roles and rights document assignments during offboarding.
+
+!!! warning
+    Permission changes can grant administrative access to customer data and configuration. Apply least privilege and log all automated changes for audit review.
+
+!!! important "Rate Limiting & Stability"
+    User and permission changes should be serialized per user. Avoid parallel role and rights document updates for the same user because the final effective permission set can be difficult to audit.
+
+## Request Examples
+
+### Create a User
+
+The create endpoint accepts optional query parameters: `parentUserId` places the new user under an existing administrator, `returnUri` supplies a callback URI for onboarding flows, and `isSSO=true` marks the user for SSO-based access.
+
+```json
+{
+  "userName": "alex.admin@example.com",
+  "firstName": "Alex",
+  "lastName": "Admin",
+  "enabled": true,
+  "roles": [
+    "USER",
+    "MANAGE_USERS"
+  ],
+  "regionalSettings": {
+    "timezoneName": "America/Denver"
+  }
+}
+```
+
+### Assign a Role
+
+`POST https://ringcx.ringcentral.com/voice/api/v1/admin/users/{userId}/roles/{roleType}`
+
+Use the `roleType` path parameter for the role being assigned.
+
+### Create a Rights Document
+
+The `RightsDocument` schema does not have `description` or `active`. Use `cascade` to control whether the document applies to child users and use `accountPermissions`, `productPermissions`, and `resourcePermissions` to declare what the document grants.
+
+```json
+{
+  "rightsDocName": "Reporting audit access",
+  "cascade": false,
+  "isMaster": false,
+  "accountPermissions": [
+    "READ"
+  ],
+  "productPermissions": [],
+  "resourcePermissions": []
+}
+```
+
+### Assign a Rights Document
+
+`POST https://ringcx.ringcentral.com/voice/api/v1/admin/rightsDocs/{rightsDocId}/assignments?userIds=987654&userIds=987655`
+
+The assignment endpoint takes one or more `userIds` query parameters. It does not accept a JSON request body.
+
+To assign multiple rights documents to one user, call `POST https://ringcx.ringcentral.com/voice/api/v1/admin/rightsDocs/assignments/{userId}?rightsDocIds=4567&rightsDocIds=4568`.
+
+### Example User Response
+
+```json
+{
+  "userId": 987654,
+  "userName": "alex.admin@example.com",
+  "firstName": "Alex",
+  "lastName": "Admin",
+  "enabled": true,
+  "roles": [
+    "USER",
+    "MANAGE_USERS"
+  ],
+  "regionalSettings": {
+    "timezoneName": "America/Denver"
+  }
+}
+```
+
+## Response and Schema Notes
+
+| Resource | Key Fields | Notes |
+| --- | --- | --- |
+| User | `userId`, `userName`, `firstName`, `lastName`, `enabled`, `regionalSettings`, `roles` | Admin portal identity and lifecycle state. |
+| Role | `roleType`, `userId`, `createdOn` | Coarse access grant. Supported role values include `SUPER_USER`, `USER`, `MANAGE_USERS`, `MANAGE_RIGHTS`, `ACCESS_SIBLINGS`, `ACCESS_AUDIT_LOG`, `ASSUME_USERS`, `REPORT_ADMINISTRATIVE_USER`, `WFO_ACCESS`, `ACCESS_GOODDATA_EDITOR`, `ACCESS_GOODDATA_ANALYST`, `ACCESS_GOODDATA_VIEWER`, and `NO_ACCESS`. |
+| Rights document | `rightsDocId`, `rightsDocName`, `ownerId`, `cascade`, `isMaster`, `accountPermissions`, `productPermissions`, `resourcePermissions`, `roleCode`, `isSystemRole` | Fine-grained administrative permissions. There is no `description` or `active` field on this resource. |
+| Assignment | `rightsDocId`, `userIds`, `rightsDocIds` | Grants rights document access to one or more users. Assignment create operations use query parameters rather than a JSON body. |
+
+## Common Errors
+
+| Status | Cause | Resolution |
+| --- | --- | --- |
+| `400 Bad Request` | Missing user fields, invalid role type, or malformed rights document. | Validate against the generated API reference before submitting. |
+| `403 Forbidden` | Caller cannot manage users, roles, or rights docs. | Grant appropriate Admin portal permission to the automation user. |
+| `404 Not Found` | User, role, or rights document ID does not exist. | List the target resource before updating or deleting. |
+| `409 Conflict` | Username, role, or assignment already exists. | Treat create operations as idempotent by reading current state first. |
+
+## Sample Implementation (Python)
+
+```python
+import requests
+
+BASE_URL = "https://ringcx.ringcentral.com/voice/api"
+
+def onboard_admin_user(token, user_name, role_type, rights_doc_id=None):
+    headers = {"Authorization": f"Bearer {token}"}
+    user = requests.post(
+        f"{BASE_URL}/v1/admin/users",
+        headers=headers,
+        json={
+            "userName": user_name,
+            "firstName": "Alex",
+            "lastName": "Admin",
+            "enabled": True,
+            "roles": ["USER"],
+            "regionalSettings": {"timezoneName": "America/Denver"},
+        },
+    )
+    user.raise_for_status()
+    user_id = user.json()["userId"]
+
+    role = requests.post(
+        f"{BASE_URL}/v1/admin/users/{user_id}/roles/{role_type}",
+        headers=headers,
+    )
+    role.raise_for_status()
+
+    if rights_doc_id is not None:
+        assignment = requests.post(
+            f"{BASE_URL}/v1/admin/rightsDocs/{rights_doc_id}/assignments",
+            headers=headers,
+            params={"userIds": [user_id]},
+        )
+        assignment.raise_for_status()
+
+    return user.json()
+```

docs/workforce/qm/index.md

@@ -12,11 +12,11 @@ When a call is ended, a call event is triggered so you can know that a call is r
 
 ## Call Details and Recordings
 
-Sometimes, you may miss an event due to server issues or connection issues.  In these cases, you can reconcile your call events with the [Call Details and Recordings](../../analytics/reports/global-call-type-detail-report.md) report. All the call details are available in this historical report including the [single channel call recording](../../analytics/reports/global-call-type-detail-report.md#call-recordings).
+Sometimes, you may miss an event due to server issues or connection issues.  In these cases, you can reconcile your call events with the [Call Details and Recordings](../../integration/reports-orig.md#interaction-metadata-media) report. All the call details are available in this historical report including the [single channel call recording](../../integration/reports-orig.md#retrieving-agent-segment-recordings-transcripts).
 
 ## Agent Reports
 
-Not all agent performance can be tracked via events. Some details like ring time, hold time, and talk time are all captured and report on after the call. You can find these report details in the [Agent Segment Metadata Report](../../analytics/reports/agent-segment-metadata-report.md). This report also includes the call recording, stored as a `WAV` file and can be retrieved 1-2 minutes after the call ends. To determine when a call ends, use the [Configuring Workforce Management](../../notifications/wfm/configure-wfm.md) to listen for End Call Events.
+Not all agent performance can be tracked via events. Some details like ring time, hold time, and talk time are all captured and report on after the call. You can find these report details in the [Agent Segment Metadata Report](../../integration/reports-orig.md#agent-segment-metadata). This report also includes the call recording, stored as a `WAV` file and can be retrieved 1-2 minutes after the call ends. To determine when a call ends, use the [Configuring Workforce Management](../../notifications/wfm/configure-wfm.md) to listen for End Call Events.
 
 ## Call Recordings