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.

{
  "errorCode": "access.denied.exception",
  "generalMessage": "You do not have permission to access this resource",
  "timestamp": 1611847650696
}

Users

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.

Rights Documents

Rights documents provide detailed administrative permissions. Use these endpoints for advanced permission management or audit tooling.

API Tokens and Auth Utilities

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.

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.

{
  "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.

{
  "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 the assignment endpoint once for each rights document ID with the same userIds value.

Example User Response

{
  "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

Common Errors

Sample Implementation (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()

• Last updated:
• Contributors