Users

Users are members of your firm that have access to Addepar. The Users API lets you view, create, and delete users, as well as update user information, tool permissions, and portfolio access.

Overview


Base route	`/v1/users`
Produces	JSON
Pagination	Yes
OAuth scopes	GET: `USERS` -- POST, PATCH, DELETE: `USERS_WRITE` (except POST `/v1/users/external_user_id_query` which requires `USERS` or `USERS_WRITE`)

📘
Access requirements
Requires the "API Access: Create, edit, and delete" and "Manage firm settings: Users and permissions" application permissions for all operations.

Resource attributes

Users are described by the attributes below. All attributes are returned in successful GET, POST, and PATCH responses.

Attribute	Description
`email`	String. The email address used for authentication. Not editable. Example: `"[email protected]"`
`first_name`	String. The user's first name. Example: `"Adam"`
`last_name`	String. The user's last name. Example: `"Smith"`
`login_method`	String. Not editable. Supported values: `email_password`, `saml`. Example: `"email_password"`
`saml_user_id`	String. Not editable. Required if `login_method` is `saml`. Example: `"asmith"`
`admin_access`	Boolean. Indicates whether the user has access to all permissions. Example: `false`
`all_data_access`	Boolean. Indicates whether the user has permission to access all current and future portfolio data. Example: `true`
`two_factor_auth_enabled`	Boolean. Indicates whether two-factor authentication is enabled. Not editable. Example: `true`
`external_user_id`	String. The firm's unique ID for the user (e.g., employee ID or HR system ID). Example: `"A67890"`

Relationships

Relationship	Description
`assigned_role`	The role that the user is assigned to.
`permissioned_entities`	The client portfolios the user has access to.
`permissioned_groups`	The groups the user has access to.

Get a user

Retrieves details for a specific user.

GET /v1/users/:id

📘
Authentication
All requests require a base64-encoded API key pair:
Authorization: Basic {base64(key_id:key_secret)}
See Access & Authentication for setup.

curl -X GET "https://{firm}.addepar.com/api/v1/users/2000" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

{
  "data": {
    "id": "2000",
    "type": "users",
    "attributes": {
      "email": "[email protected]",
      "first_name": "Adam",
      "last_name": "Smith",
      "login_method": "email_password",
      "two_factor_auth_enabled": false,
      "admin_access": true,
      "all_data_access": true
    },
    "relationships": {
      "permissioned_entities": {
        "links": {
          "self": "/v1/users/2000/relationships/permissioned_entities",
          "related": "/v1/users/2000/permissioned_entities"
        },
        "data": []
      },
      "assigned_role": {
        "links": {
          "self": "/v1/users/2000/relationships/assigned_role",
          "related": "/v1/users/2000/assigned_role"
        },
        "data": null
      },
      "permissioned_groups": {
        "links": {
          "self": "/v1/users/2000/relationships/permissioned_groups",
          "related": "/v1/users/2000/permissioned_groups"
        },
        "data": []
      }
    },
    "links": {
      "self": "/v1/users/2000"
    }
  },
  "included": []
}

{
  "errors": [
    {
      "id": "not_found",
      "status": "404",
      "title": "Not Found",
      "detail": "User with id 2000 does not exist or you do not have permission to view it."
    }
  ]
}

Response codes

200 OK -- Success
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID

Get all users

Retrieves details for all users. Results are paginated.

GET /v1/users

curl -X GET "https://{firm}.addepar.com/api/v1/users" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "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": []
        },
        "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
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have permission to view users."
    }
  ]
}

Response codes

200 OK -- Success
403 Forbidden -- Lacking permission to view users

Get current user

Retrieves details for the currently authenticated user. This is the user who created the API key used to authenticate the request.

GET /v1/users/me

curl -X GET "https://{firm}.addepar.com/api/v1/users/me" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

{
  "data": {
    "id": "22",
    "type": "users",
    "attributes": {
      "email": "[email protected]",
      "first_name": "API",
      "last_name": "User",
      "login_method": "email_password",
      "two_factor_auth_enabled": false,
      "admin_access": true,
      "all_data_access": true
    },
    "relationships": {
      "permissioned_entities": {
        "links": {
          "self": "/v1/users/22/relationships/permissioned_entities",
          "related": "/v1/users/22/permissioned_entities"
        },
        "data": []
      },
      "assigned_role": {
        "data": null
      },
      "permissioned_groups": {
        "links": {
          "self": "/v1/users/22/relationships/permissioned_groups",
          "related": "/v1/users/22/permissioned_groups"
        },
        "data": []
      }
    },
    "links": {
      "self": "/v1/users/22"
    }
  },
  "included": []
}

{
  "errors": [
    {
      "id": "unauthorized",
      "status": "401",
      "title": "Unauthorized",
      "detail": "The API key is invalid or has been revoked."
    }
  ]
}

Response codes

200 OK -- Success
401 Unauthorized -- The API key is invalid

Get a user's assigned role

Retrieves the role assigned to a user. If no role is assigned, data returns as null.

GET /v1/users/:user-id/relationships/assigned_role

curl -X GET "https://{firm}.addepar.com/api/v1/users/101/relationships/assigned_role" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

{
  "data": {
    "id": "1",
    "type": "role"
  }
}

{
  "errors": [
    {
      "id": "not_found",
      "status": "404",
      "title": "Not Found",
      "detail": "User with id 101 does not exist or you do not have permission to view it."
    }
  ]
}

Response codes

200 OK -- Success
400 Bad Request -- Invalid relationship queried
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID

Get a user's permissioned entities or groups

Retrieves a list of IDs for the client or group portfolios that the user has access to.

GET /v1/users/:user-id/relationships/permissioned_entities

GET /v1/users/:user-id/relationships/permissioned_groups

curl -X GET "https://{firm}.addepar.com/api/v1/users/5678/relationships/permissioned_groups" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

{
  "data": [
    {
      "id": "10000",
      "type": "entities"
    }
  ]
}

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid relationship queried."
    }
  ]
}

Response codes

200 OK -- Success
400 Bad Request -- Invalid relationship queried
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID

Get users by email

Retrieves details for users matching the provided email addresses.

POST /v1/users/email_query

curl -X POST "https://{firm}.addepar.com/api/v1/users/email_query" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": {
      "type": "email_query",
      "attributes": {
        "email_ids": [
          "[email protected]",
          "[email protected]"
        ]
      }
    }
  }'

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "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": []
        },
        "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
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have permission to query users."
    }
  ]
}

Response codes

200 OK -- Success
403 Forbidden -- User lacks sufficient application permissions

Get users by external user ID

Retrieves details for users matching the provided external user IDs.

POST /v1/users/external_user_id_query

curl -X POST "https://{firm}.addepar.com/api/v1/users/external_user_id_query" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": {
      "type": "external_user_id_query",
      "attributes": {
        "external_user_ids": [
          "A12345",
          "A67890"
        ]
      }
    }
  }'

{
  "data": [
    {
      "id": "1000",
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Adam",
        "last_name": "Smith",
        "login_method": "email_password",
        "two_factor_auth_enabled": true,
        "admin_access": false,
        "all_data_access": true,
        "external_user_id": "A12345"
      },
      "relationships": {
        "permissioned_entities": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_entities",
            "related": "/v1/users/1000/permissioned_entities"
          },
          "data": []
        },
        "assigned_role": {
          "links": {
            "self": "/v1/users/1000/relationships/assigned_role",
            "related": "/v1/users/1000/assigned_role"
          },
          "data": []
        },
        "permissioned_groups": {
          "links": {
            "self": "/v1/users/1000/relationships/permissioned_groups",
            "related": "/v1/users/1000/permissioned_groups"
          },
          "data": []
        }
      },
      "links": {
        "self": "/v1/users/1000"
      }
    },
    {
      "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": []
        },
        "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
  }
}

{
  "errors": [
    {
      "id": "forbidden",
      "status": "403",
      "title": "Forbidden",
      "detail": "You do not have permission to query users."
    }
  ]
}

Response codes

200 OK -- Success
403 Forbidden -- User lacks sufficient application permissions

Create a user

By default, users are created in custom mode with no permissions. You can keep them in custom mode and manually assign permissions in the Addepar application.

To assign user permissions based on a specific role, use the Edit a user's role endpoint or the Assign Role to Users method in the Roles API.

POST /v1/users

curl -X POST "https://{firm}.addepar.com/api/v1/users" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": {
      "type": "users",
      "attributes": {
        "email": "[email protected]",
        "first_name": "Example",
        "last_name": "User",
        "login_method": "email_password"
      }
    }
  }'

{
  "data": {
    "id": "82",
    "type": "users",
    "attributes": {
      "email": "[email protected]",
      "first_name": "Example",
      "last_name": "User",
      "login_method": "email_password",
      "two_factor_auth_enabled": false,
      "admin_access": false,
      "all_data_access": false
    },
    "relationships": {
      "permissioned_entities": {
        "links": {
          "self": "/v1/users/82/relationships/permissioned_entities",
          "related": "/v1/users/82/permissioned_entities"
        },
        "data": []
      },
      "assigned_role": {
        "links": {
          "self": "/v1/users/82/relationships/assigned_role",
          "related": "/v1/users/82/assigned_role"
        },
        "data": null
      },
      "permissioned_groups": {
        "links": {
          "self": "/v1/users/82/relationships/permissioned_groups",
          "related": "/v1/users/82/permissioned_groups"
        },
        "data": []
      }
    },
    "links": {
      "self": "/v1/users/82"
    }
  },
  "included": []
}

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "The email address provided is already in use."
    }
  ]
}

Response codes

201 Created -- Success
400 Bad Request -- Invalid email provided
400 Bad Request -- SAML User ID already in use
400 Bad Request -- Email is already in use
403 Forbidden -- User lacks sufficient application permissions
409 Conflict -- A duplicate external_user_id exists for the firm

Add user's access to entities or groups

Grants a user access to a specific client or group of portfolios.

POST /v1/users/:id/relationships/permissioned_entities

POST /v1/users/:id/relationships/permissioned_groups

curl -X POST "https://{firm}.addepar.com/api/v1/users/101/relationships/permissioned_groups" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": [
      {
        "id": "10",
        "type": "groups"
      }
    ]
  }'

HTTP/1.1 204 No Content

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "One or more client IDs do not exist or you do not have permission to access them."
    }
  ]
}

Response codes

204 No Content -- Success
400 Bad Request -- Nonexistent or non-permissioned client IDs
404 Not Found -- Nonexistent or non-permissioned user ID

Edit a user

Updates the user's first_name, last_name, all_data_access, or admin_access.

PATCH /v1/users/:id

curl -X PATCH "https://{firm}.addepar.com/api/v1/users/621500" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": {
      "type": "users",
      "id": "621500",
      "attributes": {
        "first_name": "Second",
        "last_name": "User"
      }
    }
  }'

{
  "data": {
    "id": "621500",
    "type": "users",
    "attributes": {
      "email": "[email protected]",
      "first_name": "Second",
      "last_name": "User",
      "login_method": "email_password",
      "two_factor_auth_enabled": false,
      "admin_access": false,
      "all_data_access": false
    },
    "relationships": {
      "permissioned_entities": {
        "links": {
          "self": "/v1/users/621500/relationships/permissioned_entities",
          "related": "/v1/users/621500/permissioned_entities"
        },
        "data": []
      },
      "assigned_role": {
        "links": {
          "self": "/v1/users/621500/relationships/assigned_role",
          "related": "/v1/users/621500/assigned_role"
        },
        "data": {
          "type": "roles",
          "id": "455914"
        }
      },
      "permissioned_groups": {
        "links": {
          "self": "/v1/users/621500/relationships/permissioned_groups",
          "related": "/v1/users/621500/permissioned_groups"
        },
        "data": [
          {
            "type": "groups",
            "id": "1020871"
          },
          {
            "type": "groups",
            "id": "1021710"
          }
        ]
      }
    },
    "links": {
      "self": "/v1/users/621500"
    }
  },
  "included": []
}

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "Cannot update relationships through this endpoint. Use the relationships endpoint instead."
    }
  ]
}

Response codes

200 OK -- Success
400 Bad Request -- Attempted to update relationships
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID
409 Conflict -- A duplicate external_user_id exists for the firm

Edit a user's role

Updates the role assigned to a user.

📘
Note
Before using this endpoint, you must assign a role to a user in the Addepar application.

PATCH /v1/users/:id/relationships/assigned_role

curl -X PATCH "https://{firm}.addepar.com/api/v1/users/101/relationships/assigned_role" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": {
      "id": "1",
      "type": "role"
    }
  }'

HTTP/1.1 204 No Content

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "Role with id 1 does not exist or you do not have permission to assign it."
    }
  ]
}

Response codes

204 No Content -- Success
400 Bad Request -- Nonexistent or non-permissioned role ID
404 Not Found -- Nonexistent or non-permissioned user ID

Delete a user

Removes a specified user from the firm.

⚠️
Irreversible
This operation cannot be undone.

DELETE /v1/users/:id

curl -X DELETE "https://{firm}.addepar.com/api/v1/users/101" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}"

HTTP/1.1 204 No Content

{
  "errors": [
    {
      "id": "not_found",
      "status": "404",
      "title": "Not Found",
      "detail": "User with id 101 does not exist or you do not have permission to delete it."
    }
  ]
}

Response codes

204 No Content -- Success
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID

Delete a user's access to entities or groups

Removes a user's access to specific client and group portfolios.

⚠️
Irreversible
This operation cannot be undone.

DELETE /v1/users/:id/relationships/permissioned_entities

DELETE /v1/users/:id/relationships/permissioned_groups

curl -X DELETE "https://{firm}.addepar.com/api/v1/users/101/relationships/permissioned_groups" \
  -H "Authorization: Basic {base64(key_id:key_secret)}" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Addepar-Firm: {firm_id}" \
  -d '{
    "data": [
      {
        "id": "1",
        "type": "groups"
      }
    ]
  }'

HTTP/1.1 204 No Content

{
  "errors": [
    {
      "id": "bad_request",
      "status": "400",
      "title": "Bad Request",
      "detail": "Invalid relationship queried."
    }
  ]
}

Response codes

204 No Content -- Success
400 Bad Request -- Invalid relationship queried
403 Forbidden -- User lacks sufficient application permissions
404 Not Found -- Nonexistent or non-permissioned user ID

📘
Related resources

Roles API -- Manage role definitions and assignments

Pagination -- Paginate through list responses

Access & Authentication -- API key setup and authentication