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

N/A

Resource Overview

The attributes below will always appear in GET, POST, and PATCH responses.

Attribute

Description

Example

e

The name of the role. String.

"

Relationships

Relationship

Description

s

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: Success
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 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: Success
  • 403 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: Success
  • 400 Bad Request: Invalid relationship queried
  • 400 Bad Request: Include parameter not supported
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 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: Success
  • 400 Bad Request: Invalid relationship queried
  • 400 Bad Request: Include parameter not supported
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 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: Success
  • 400 Bad Request: Nonexistent/non-permissioned user/attribute ID
  • 404 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: Success
  • 400 Bad Request: Nonexistent/non-permissioned user/attribute ID
  • 404 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: Success
  • 400 Bad Request: Failed to provide an id or tried to delete a role that cannot be deleted
  • 403 Forbidden: User lacks sufficient application permissions
  • 404 Not found: No role exists with the provided id in the firm

Updated 18 days ago


What's Next

Users

Roles


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.