Roles
Roles represent standard sets of permissions available to your firm. Use the Roles API to view your firm's roles, and add or remove the users assigned to each role.
| Base Route | /v1/roles |
| Endpoints | GET /v1/roles/:id /v1/roles /v1/roles/:id/relationships/assigned_users /v1/roles/:id/assigned_users POST /v1/roles/:id/relationships/assigned_users PATCH /v1/roles/:id/relationships/assigned_users DELETE /v1/roles/:id/relationships/assigned_users |
| Produces | JSON |
| Pagination | Yes |
| Application Permissions Required | "API Access: Create, edit, and delete" "Manage firm settings: Users and permissions" for all operations. |
| OAuth Scopes | GETUSERS and USERS_WRITEPOST, PATCH, and DELETE USERS_WRITE |
Resource Overview
The attributes below will always appear in GET, POST, and PATCH responses.
| Attribute | Description | Example |
|---|---|---|
name | The name of the role. String. | "Platform Team" |
Relationships
| Relationship | Description |
|---|---|
assigned_users | Users assigned to the role. |
"relationships":{
"assigned_users":{
"links":{
"self":"/v1/roles/455914/relationships/assigned_users",
"related":"/v1/roles/455914/assigned_users"
},
"data":[
{
"type":"users",
"id":"621500"
}
]
}
}
Note
Creation, deletion, and modification of roles are done from within the application. Roles must be created in the application before the API can be used to update its members.
Get a Role
Returns the details for a specific role.
GET /v1/roles/:id
Example:
GET https://examplefirm.addepar.com/api/v1/roles/80
HTTP/1.1 200
{
"data": {
"id": "80",
"type": "roles",
"attributes": {
"name": "Advisor Role”
},
"relationships": {
"assigned_users": {
"links": {
"self": "/v1/roles/80/relationships/assigned_users",
"related": "/v1/roles/80/assigned_users"
},
"data": [
{
"type": "users",
"id": "101"
}
]
}
},
"links": {
"self": "/v1/roles/80"
}
}
Responses
200 OK: Success403 Forbidden: User lacks sufficient application permissions404 Not found: No role exists with the provided ID in the firm
Get All Roles
Returns a list of all roles at the firm.
GET /v1/roles
Example:
GET https://examplefirm.addepar.com/api/v1/roles
HTTP/1.1 200
{
"data": {
"id": "80",
"type": "roles",
"attributes": {
"name": "Advisor Role”
},
"relationships": {
"assigned_users": {
"links": {
"self": "/v1/roles/80/relationships/assigned_users",
"related": "/v1/roles/80/assigned_users"
},
"data": [
{
"type": "users",
"id": "101"
}
]
}
},
"links": {
"self": "/v1/roles/80"
}
},
"data": {
"id": "90",
"type": "roles",
"attributes": {
"name": "Administrator Role”
},
"relationships": {
"assigned_users": {
"links": {
"self": "/v1/roles/90/relationships/assigned_users",
"related": "/v1/roles/90/assigned_users"
},
"data": [
{
"type": "users",
"id": "102"
}
]
}
},
"links": {
"self": "/v1/roles/90"
}
}
}
Response Codes:
200 OK: Success403 Forbidden: User lacks sufficient application permissions
Get a Role's Users
Returns a list of IDs for all users assigned to a specific role.
GET /v1/roles/:id/relationships/assigned_users
Example:
GET https://examplefirm.com.addepar.com/api/v1/roles/80/relationships/assigned_users
HTTP/1.1 200
{
"data": [
{
"id": "2000",
"type": "users"
}
]
}
Response Codes:
200 OK: Success400 Bad Request: Invalid relationship queried400 Bad Request: Include parameter not supported403 Forbidden: User lacks sufficient application permissions404 Not Found: Nonexistent/non-permissioned role ID
Get a Role's User Details
Returns details about the users assigned to a specific role.
GET /v1/roles/:id/assigned_users
Example:
GET https://examplefirm.addepar.com/api/v1/roles/80/assigned_users
HTTP/1.1 200
{
"id": "2000",
"type": "users",
"attributes": {
"email": "[email protected]",
"first_name": "Jane",
"last_name": "Smith",
"login_method": "email_password",
"two_factor_auth_enabled": true,
"admin_access": false,
"all_data_access": false,
"external_user_id": "A67890"
},
"relationships": {
"permissioned_entities": {
"links": {
"self": "/v1/users/2000/relationships/permissioned_entities",
"related": "/v1/users/2000/permissioned_entities"
},
"data": [
{
"type": "entities",
"id": 10000
},
{
"type": "entities",
"id": 10001
}
]
},
"assigned_role": {
"links": {
"self": "/v1/users/2000/relationships/assigned_role",
"related": "/v1/users/2000/assigned_role"
},
"data": [
{
"type": "roles",
"id": "80"
}
]
},
"permissioned_groups": {
"links": {
"self": "/v1/users/2000/relationships/permissioned_groups",
"related": "/v1/users/2000/permissioned_groups"
},
"data": [
{
"type": "entities",
"id": 20000
},
{
"type": "entities",
"id": 20001
}
]
}
},
"links": {
"self": "/v1/users/2000"
}
}
],
"links": {
"next": null
}
}
Response Codes:
200 OK: Success400 Bad Request: Invalid relationship queried400 Bad Request: Include parameter not supported403 Forbidden: User lacks sufficient application permissions404 Not Found: Nonexistent/non-permissioned role ID
Assign Users to a Role
If a user is already assigned to a role, calling this endpoint will overwrite the role, and assign the user a new role.
POST /v1/roles/:id/relationships/assigned_users
Example:
POST https://examplefirm.addepar.com/api/v1/roles/90/relationships/assigned_users
{
"data": [
{
"id": "2000",
"type": "users"
}
]
}
HTTP/1.1 204
Response Codes:
204 No Content: Success400 Bad Request: Nonexistent/non-permissioned user/attribute ID404 Not Found: Nonexistent/non-permissioned role ID
Update Users Assigned to a Role
Updates the specified users assigned to a role.
PATCH /v1/roles/:id/relationships/assigned_users
Example:
PATCH https://examplefirm.addepar.com/api/v1/roles/80/relationships/assigned_users
{
"data": [
{
"id": "2000",
"type": "users"
}
]
}
HTTP/1.1 204
Response Codes:
204 No Content: Success400 Bad Request: Nonexistent/non-permissioned user/attribute ID404 Not Found: Nonexistent/non-permissioned user ID
Remove Users from a Role
Removes a specified user from a role.
DELETE /v1/roles/:id/relationships/assigned_users
Example:
DELETE https://examplefirm.addepar.com/api/v1/roles/80/relationships/assigned_users
{
"data": [
{
"id": "2000",
"type": "users"
}
]
}
HTTP/1.1 204
Responses:
204 No Content: Success400 Bad Request: Failed to provide an id or tried to delete a role that cannot be deleted403 Forbidden: User lacks sufficient application permissions404 Not found: No role exists with the provided id in the firm
Updated over 1 year ago