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 POST PATCH DELETE |
| Produces | JSON |
| Pagination | Yes |
| Application Permissions Required | "API Access: Create, edit, and delete" "Manage firm settings: Users and permissions" for all operations. |
| OAuth Scopes | GET POST, PATCH, and DELETE |
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"
}
]
}
}
NoteCreation, 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/80HTTP/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/rolesHTTP/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_usersHTTP/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_usersHTTP/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 204Response 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 204Response 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 204Responses:
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 27 days ago