> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/api/readme/users.md). # Users Use these operations to retrieve user role assignments across your Cortex workspace. ### Required permissions Your API token must have the `View Roles` permission. {% hint style="info" %} Some built-in API key roles (`VIWER`, `USER`, and `MANAGER`) do not include `View Roles`. To call this endpoint with an API key, use an `ADMIN` key or create a new one and assign it a [custom role](https://docs.cortex.io/docs/walkthroughs/workspace-settings/permissioning/custom-roles) that grants `View Roles`. {% endhint %} ## Operations ## List user role assignments > Returns the role assignments for every user in your Cortex tenant, intended for access reviews and access governance reporting. Each entry lists the user along with their assigned built-in (BASIC) and CUSTOM roles. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting. ```json {"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"UserRoleAssignmentsResponse":{"required":["page","total","totalPages","users"],"type":"object","properties":{"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"},"users":{"type":"array","description":"User role assignments for the current page","items":{"$ref":"#/components/schemas/UserRoleAssignment"}}}},"UserRoleAssignment":{"required":["email","name","roles"],"type":"object","properties":{"email":{"type":"string","description":"Email address of the user"},"name":{"type":"string","description":"Display name of the user"},"roles":{"type":"array","description":"Roles assigned to the user","items":{"$ref":"#/components/schemas/AssignedRole"}}},"description":"User role assignments for the current page"},"AssignedRole":{"required":["type"],"type":"object","properties":{"name":{"type":"string","description":"Display name of the custom role; present only when type is CUSTOM"},"role":{"type":"string","description":"Name of the built-in role; present only when type is BASIC"},"tag":{"type":"string","description":"Tag of the custom role; present only when type is CUSTOM"},"type":{"type":"string","description":"Whether this is a built-in (BASIC) or CUSTOM role","enum":["BASIC","CUSTOM"]}},"description":"Roles assigned to the user"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/users/roles":{"get":{"description":"Returns the role assignments for every user in your Cortex tenant, intended for access reviews and access governance reporting. Each entry lists the user along with their assigned built-in (BASIC) and CUSTOM roles. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting.","operationId":"getUserRoleAssignments","parameters":[{"description":"Filter to specific users by email. Provide a comma-separated list to request multiple users (e.g. ?email=a@acme.com,b@acme.com). Matching is case-insensitive. Omit to return all users.","in":"query","name":"email","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRoleAssignmentsResponse"}}},"description":"Successfully retrieved user role assignments"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Authentication required"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Caller does not have the View Roles permission"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List user role assignments","tags":["Users"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cortex.io/api/readme/users.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.