> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: 4f004537-9712-40c1-b207-b5cdf3896d3d
---
# Retrieves the roles on an account
> Retrieve a list of user roles available in your HubSpot account. This endpoint provides information about the different permission sets that can be assigned to users, which is useful for managing user access and permissions within the account.
export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
;
};
## OpenAPI
````yaml specs/2026-09-beta/settings-user-provisioning-v2026-09-beta.json GET /settings/users/2026-09-beta/roles
openapi: 3.0.1
info:
title: Settings User Provisioning
description: Basepom for all HubSpot Projects
version: 2026-09-beta
x-hubspot-product-tier-requirements:
marketing: FREE
sales: FREE
service: FREE
cms: FREE
commerce: FREE
crmHub: FREE
dataHub: FREE
servers:
- url: https://api.hubapi.com
security: []
tags:
- name: Basic
- name: Roles
- name: Seats
- name: Teams
- name: Users
paths:
/settings/users/2026-09-beta/roles:
get:
tags:
- Roles
summary: Retrieves the roles on an account
description: >-
Retrieve a list of user roles available in your HubSpot account. This
endpoint provides information about the different permission sets that
can be assigned to users, which is useful for managing user access and
permissions within the account.
operationId: get-/settings/users/2026-09-beta/roles
parameters: []
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: >-
#/components/schemas/CollectionResponsePublicPermissionSetNoPaging
default:
$ref: '#/components/responses/Error'
description: ''
security:
- oauth2:
- settings.users.read
- oauth2:
- crm.objects.users.read
components:
schemas:
CollectionResponsePublicPermissionSetNoPaging:
required:
- results
type: object
properties:
results:
type: array
description: >-
An array of PublicPermissionSet objects, each representing a
specific permission set. This property is required.
items:
$ref: '#/components/schemas/PublicPermissionSet'
PublicPermissionSet:
required:
- id
- name
- requiresBillingWrite
type: object
properties:
id:
type: string
description: The unique identifier for the permission set. It is a string.
name:
type: string
description: The name of the permission set. It is a string.
requiresBillingWrite:
type: boolean
description: >-
A boolean indicating whether the permission set requires billing
write access.
Error:
required:
- category
- correlationId
- message
type: object
properties:
category:
type: string
description: The error category, providing a general classification of the error.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object with
additional properties that are arrays of strings.
example: >-
{invalidPropertyName=[propertyValue], missingScopes=[scope1,
scope2]}
correlationId:
type: string
description: >-
A unique identifier for the request. Include this value with any
error reports or support tickets. It is formatted as a UUID.
format: uuid
example: aeb5f871-7f07-4993-9211-075dc63e7cbf
errors:
type: array
description: >-
Further information about the error, represented as an array of
ErrorDetail objects.
items:
$ref: '#/components/schemas/ErrorDetail'
links:
type: object
additionalProperties:
type: string
description: >-
A map of link names to associated URIs containing documentation
about the error or recommended remediation steps.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate.
example: An error occurred
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
example:
message: Invalid input (details will vary based on the error)
correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
category: VALIDATION_ERROR
links:
knowledge-base: https://www.hubspot.com/products/service/knowledge-base
ErrorDetail:
required:
- message
type: object
properties:
code:
type: string
description: The status code associated with the error detail.
context:
type: object
additionalProperties:
type: array
items:
type: string
description: >-
Context about the error condition, represented as an object with
additional properties. Each property is an array of strings
providing further context.
example: '{missingScopes=[scope1, scope2]}'
in:
type: string
description: The name of the field or parameter in which the error was found.
message:
type: string
description: >-
A human readable message describing the error along with remediation
steps where appropriate. This is a required field.
subCategory:
type: string
description: >-
A specific category that contains more specific detail about the
error.
responses:
Error:
description: An error occurred.
content:
'*/*':
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.hubspot.com/oauth/authorize
tokenUrl: https://api.hubapi.com/oauth/v1/token
scopes:
crm.objects.users.write: ''
settings.billing.write: ''
settings.users.read: ''
settings.users.teams.read: ''
````
{product.name} -
{product.level}
)}