User Permissions

Manage user permissions and access controls within Audian accounts.

Overview

User permissions determine what actions a user can perform in the Audian platform. Permissions are granted based on user roles and can be customized for specific users.

Permission Model

Audian uses a role-based access control (RBAC) model combined with fine-grained permissions:

Roles: Default permission sets (admin, manager, user, operator, agent)
Permissions: Individual granular permissions
Custom Roles: Create custom role combinations
Inheritance: Permissions inherited from parent accounts

Available Permissions

Call Permissions

Permission	Description
`calls.make`	Make outbound calls
`calls.receive`	Receive inbound calls
`calls.transfer`	Transfer calls to other users
`calls.conference`	Create conference calls
`calls.hold`	Place calls on hold
`calls.mute`	Mute microphone during calls
`calls.record`	Record calls

Voicemail Permissions

Permission	Description
`voicemail.access`	Access personal voicemail
`voicemail.manage`	Manage voicemail settings
`voicemail.record`	Record voicemail greetings
`voicemail.delete`	Delete voicemail messages

Contact Permissions

Permission	Description
`contacts.view`	View contacts
`contacts.manage`	Create/edit/delete contacts
`contacts.import`	Import contact lists
`contacts.export`	Export contacts

Presence Permissions

Permission	Description
`presence.view`	View own presence
`presence.manage`	Update own presence
`presence.viewOthers`	View other users' presence
`presence.manageTeam`	Manage team presence

Device Permissions

Permission	Description
`devices.view`	View own devices
`devices.manage`	Configure own devices
`devices.viewAll`	View all account devices
`devices.manageAll`	Configure all account devices
`devices.provision`	Provision new devices

Recording Permissions

Permission	Description
`recordings.access`	Access own recordings
`recordings.viewAll`	View all account recordings
`recordings.delete`	Delete recordings
`recordings.export`	Export recordings

Admin Permissions

Permission	Description
`admin.users`	Manage user accounts
`admin.devices`	Manage all devices
`admin.account`	Manage account settings
`admin.billing`	Manage billing
`admin.audit`	View audit logs
`admin.permissions`	Manage permissions

User Roles

Admin Role

Full account access:

{
  "role": "admin",
  "permissions": [
    "calls.*",
    "voicemail.*",
    "contacts.*",
    "presence.*",
    "devices.*",
    "recordings.*",
    "admin.*"
  ]
}

Manager Role

Team management access:

{
  "role": "manager",
  "permissions": [
    "calls.make",
    "calls.receive",
    "calls.transfer",
    "calls.conference",
    "voicemail.access",
    "contacts.view",
    "contacts.manage",
    "presence.viewOthers",
    "devices.view",
    "recordings.access",
    "admin.users"
  ]
}

Standard User Role

Basic user access:

{
  "role": "user",
  "permissions": [
    "calls.make",
    "calls.receive",
    "calls.transfer",
    "voicemail.access",
    "contacts.view",
    "presence.view",
    "devices.view"
  ]
}

Operator Role

Receptionist/operator:

{
  "role": "operator",
  "permissions": [
    "calls.make",
    "calls.receive",
    "calls.transfer",
    "calls.conference",
    "presence.viewOthers",
    "devices.view"
  ]
}

Endpoints

GET /v1/accounts/{accountId}/users/{userId}/permissions
POST /v1/accounts/{accountId}/users/{userId}/permissions
PATCH /v1/accounts/{accountId}/users/{userId}/permissions
GET /v1/accounts/{accountId}/roles
POST /v1/accounts/{accountId}/roles

Get User Permissions

Retrieve permissions for a user.

Endpoint

GET https://api.audian.com:8443/v2/accounts/{accountId}/users/{userId}/permissions

Example

curl -X GET https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456/permissions \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response

{
  "userId": "user_123456",
  "role": "standard",
  "roleDescription": "Standard User - Basic calling features",
  "permissions": [
    "calls.make",
    "calls.receive",
    "calls.transfer",
    "voicemail.access",
    "contacts.view",
    "presence.view",
    "devices.view"
  ],
  "customPermissions": [],
  "inheritedPermissions": [],
  "lastModified": "2023-10-20T10:00:00Z"
}

Set User Permissions

Assign permissions to a user.

Endpoint

POST https://api.audian.com:8443/v2/accounts/{accountId}/users/{userId}/permissions

Request Body

Parameter	Type	Required	Description
`role`	string	Yes	Role name or "custom"
`permissions`	array	No	Custom permission list

Example - Assign Role

curl -X POST https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456/permissions \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "role": "operator"
  }'

Example - Custom Permissions

curl -X POST https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456/permissions \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "role": "custom",
    "permissions": [
      "calls.make",
      "calls.receive",
      "calls.transfer",
      "calls.conference",
      "voicemail.access",
      "voicemail.manage",
      "contacts.view",
      "contacts.manage",
      "presence.view",
      "devices.view"
    ]
  }'

Response

{
  "userId": "user_123456",
  "role": "custom",
  "permissions": [
    "calls.make",
    "calls.receive",
    "calls.transfer",
    "calls.conference",
    "voicemail.access",
    "voicemail.manage",
    "contacts.view",
    "contacts.manage",
    "presence.view",
    "devices.view"
  ],
  "updated": true,
  "lastModified": "2023-10-20T10:35:00Z"
}

Update Permissions

Modify existing user permissions.

Endpoint

PATCH https://api.audian.com:8443/v2/accounts/{accountId}/users/{userId}/permissions

Request Body

Parameter	Type	Description
`addPermissions`	array	Permissions to add
`removePermissions`	array	Permissions to remove
`role`	string	Change to new role

Example - Add Permission

curl -X PATCH https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456/permissions \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "addPermissions": ["calls.record", "recordings.access"]
  }'

Example - Remove Permission

curl -X PATCH https://api.audian.com:8443/v2/accounts/acc_1234567890/users/user_123456/permissions \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "removePermissions": ["admin.users"]
  }'

Custom Roles

Get All Roles

curl -X GET https://api.audian.com:8443/v2/accounts/acc_1234567890/roles \
  -H "X-Auth-Token: YOUR_API_TOKEN"

Response

{
  "defaultRoles": [
    {
      "name": "admin",
      "description": "Administrator with full access",
      "permissions": [/* all permissions */]
    },
    {
      "name": "manager",
      "description": "Team manager",
      "permissions": [/* manager permissions */]
    },
    {
      "name": "user",
      "description": "Standard user",
      "permissions": [/* user permissions */]
    },
    {
      "name": "operator",
      "description": "Operator/Receptionist",
      "permissions": [/* operator permissions */]
    }
  ],
  "customRoles": [
    {
      "id": "role_custom_001",
      "name": "Senior Agent",
      "description": "Call center agent with supervisor rights",
      "permissions": [/* custom permissions */]
    }
  ]
}

Create Custom Role

curl -X POST https://api.audian.com:8443/v2/accounts/acc_1234567890/roles \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: YOUR_API_TOKEN" \
  -d '{
    "name": "Senior Agent",
    "description": "Call center agent with supervisor rights",
    "permissions": [
      "calls.make",
      "calls.receive",
      "calls.transfer",
      "calls.conference",
      "voicemail.access",
      "contacts.view",
      "presence.viewOthers",
      "devices.view",
      "recordings.access"
    ]
  }'

JavaScript/Node.js Example

const axios = require('axios');

async function setUserPermissions(accountId, userId, role, customPermissions) {
  try {
    const data = {
      role: customPermissions ? 'custom' : role
    };
    
    if (customPermissions) {
      data.permissions = customPermissions;
    }
    
    const response = await axios.post(
      `https://api.audian.com:8443/v2/accounts/${accountId}/users/${userId}/permissions`,
      data,
      {
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_API_TOKEN'
        }
      }
    );
    
    console.log('Permissions updated:', response.data);
    return response.data;
  } catch (error) {
    console.error('Error:', error.response.data);
  }
}

// Usage
setUserPermissions('acc_1234567890', 'user_123456', 'operator');

Permission Best Practices

Principle of Least Privilege: Grant only necessary permissions
Role-Based: Use predefined roles when possible
Regular Review: Audit permissions quarterly
Separation of Duties: Separate admin and operational roles
Documentation: Document why specific permissions are granted
Monitoring: Monitor permission usage and abuse

Permission Hierarchy

Wildcard (*)
└── Granular Permissions
    ├── calls.*
    │   ├── calls.make
    │   ├── calls.receive
    │   ├── calls.transfer
    │   └── calls.record
    ├── voicemail.*
    ├── contacts.*
    ├── devices.*
    └── admin.*

Status Codes

Code	Description
`200`	Success
`201`	Created
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Not found
`409`	Conflict
`500`	Server error

Overview​

Permission Model​

Available Permissions​

Call Permissions​

Voicemail Permissions​

Contact Permissions​

Presence Permissions​

Device Permissions​

Recording Permissions​

Admin Permissions​

User Roles​

Admin Role​

Manager Role​

Standard User Role​

Operator Role​

Endpoints​

Get User Permissions​

Endpoint​

Example​

Response​

Set User Permissions​

Endpoint​

Request Body​

Example - Assign Role​

Example - Custom Permissions​

Response​

Update Permissions​

Endpoint​

Request Body​

Example - Add Permission​

Example - Remove Permission​

Custom Roles​

Get All Roles​

Response​

Create Custom Role​

JavaScript/Node.js Example​

Permission Best Practices​

Permission Hierarchy​

Status Codes​

Related Documentation​

Overview

Permission Model

Available Permissions

Call Permissions

Voicemail Permissions

Contact Permissions

Presence Permissions

Device Permissions

Recording Permissions

Admin Permissions

User Roles

Admin Role

Manager Role

Standard User Role

Operator Role

Endpoints

Get User Permissions

Endpoint

Example

Response

Set User Permissions

Endpoint

Request Body

Example - Assign Role

Example - Custom Permissions

Response

Update Permissions

Endpoint

Request Body

Example - Add Permission

Example - Remove Permission

Custom Roles

Get All Roles

Response

Create Custom Role

JavaScript/Node.js Example

Permission Best Practices

Permission Hierarchy

Status Codes

Related Documentation