> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a role > Returns a single role by ID. Pass a `system_`-prefixed ID to fetch a built-in role, or an ObjectId to fetch a custom role. Get a single role (system or custom) **Permission:** Org **admin**, or a user with `update_users`. Denials read `View Roles`. **Not callable with an API key.** Requires an org **admin** or the `update_users` permission. Service accounts can be neither (`update_users` is denied to them and they cannot be admin), so every API key gets `403`. ## OpenAPI ````yaml /api-reference/specs/roles.json get /api/roles/{id} openapi: 3.1.0 info: title: ConveYour API — Roles description: Manage RBAC roles — named permission sets assigned to users within an org. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Roles description: Manage RBAC roles — named permission sets assigned to users within an org. paths: /api/roles/{id}: get: tags: - Roles summary: Get a role description: >- Returns a single role by ID. Pass a `system_`-prefixed ID to fetch a built-in role, or an ObjectId to fetch a custom role. Get a single role (system or custom) **Permission:** Org **admin**, or a user with `update_users`. Denials read `View Roles`. **Not callable with an API key.** Requires an org **admin** or the `update_users` permission. Service accounts can be neither (`update_users` is denied to them and they cannot be admin), so every API key gets `403`. operationId: getASingleRoleSystemOrCustom parameters: - name: id in: path required: true description: The id identifier. schema: type: string - $ref: '#/components/parameters/teams' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: oneOf: - $ref: '#/components/schemas/SystemRole' - $ref: '#/components/schemas/Role' description: >- A system role when the id is a system role id, otherwise the stored custom role. example: status: ok message: Role found data: id: 64a1b2c3d4e5f6a7b8c9d0e1 name: Regional Manager slug: regional_manager description: Manages contacts and reports for a region. permissions: - contacts - add_contacts - reports type: custom is_editable: true '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. SystemRole: type: object description: >- A built-in role from a template. It is NOT a stored record — it has no org_id, source_template, created_at or updated_at. properties: id: type: string description: Synthetic system role ID derived from the slug. slug: type: string description: Template slug. name: type: string description: Display name. description: type: string description: Role description. permissions: type: array items: type: string description: Permission slugs granted. type: type: string enum: - system description: Always 'system'. is_editable: type: boolean enum: - false description: Always false — system roles cannot be edited. required: - id - slug - name - description - permissions - type - is_editable Role: type: object description: >- A custom role. Custom roles carry `type: "custom"` and `is_editable: true`. properties: id: type: string description: Role ID. org_id: type: integer description: Owning organization. name: type: string description: Display name. slug: type: string description: Machine-readable identifier. description: type: string description: What the role is for. permissions: type: array description: Permission slugs granted by this role. source_template: type: string description: Template the role was created from, if any. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. type: type: string enum: - custom description: Always 'custom' for a stored role. is_editable: type: boolean description: Always true for a custom role. required: - name - slug responses: Forbidden: description: >- The token is missing or invalid, or the service account behind it lacks the permission this endpoint requires. content: application/json: example: status: failed message: Lacking necessary permission add_contacts data: permission: add_contacts NotFound: description: No record matched the supplied ID. content: application/json: example: status: failed message: Contact not found data: [] securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.