Guides

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.

Overview

Base route/v1/roles
ProducesJSON
PaginationYes
OAuth scopesUSERS, USERS_WRITE

Access requirements

  • Application permission: "API Access: Create, edit, and delete"
  • Application permission: "Manage firm settings: Users and permissions" for all operations.

Endpoints

MethodEndpoint
GET/v1/roles/:id
GET/v1/roles
GET/v1/roles/:id/relationships/assigned_users
GET/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

Resource Attributes

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

AttributeDescription
nameThe name of the role. String.

Relationships

RelationshipDescription
assigned_usersUsers 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"
      }
    ]
  }
}

info

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

Authentication

This endpoint requires a valid API key or OAuth token with the USERS scope. All requests must include the Authorization and Addepar-Firm headers.

Example:

curl -X GET "https://{firm}.addepar.com/api/v1/roles/80" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"
{
    "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:

curl -X GET "https://{firm}.addepar.com/api/v1/roles" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"
{
    "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"
            }
        },
        {
            "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"
            }
        }
    ]
}

Responses

  • 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:

curl -X GET "https://{firm}.addepar.com/api/v1/roles/80/relationships/assigned_users" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"
{
    "data": [
        {
            "id": "2000",
            "type": "users"
        }
    ]
}

Responses

  • 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:

curl -X GET "https://{firm}.addepar.com/api/v1/roles/80/assigned_users" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json"
{
    "data": [
        {
            "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
    }
}

Responses

  • 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:

curl -X POST "https://{firm}.addepar.com/api/v1/roles/90/relationships/assigned_users" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": [
        {
            "id": "2000",
            "type": "users"
        }
    ]
}'
HTTP/1.1 204 No Content

Responses

  • 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:

curl -X PATCH "https://{firm}.addepar.com/api/v1/roles/80/relationships/assigned_users" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": [
        {
            "id": "2000",
            "type": "users"
        }
    ]
}'
HTTP/1.1 204 No Content

Responses

  • 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:

curl -X DELETE "https://{firm}.addepar.com/api/v1/roles/80/relationships/assigned_users" \
  -H "Authorization: Basic {credentials}" \
  -H "Addepar-Firm: 1" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": [
        {
            "id": "2000",
            "type": "users"
        }
    ]
}'
HTTP/1.1 204 No Content

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

Related Resources

Updated 6 days ago

What’s Next

Did this page help you?