> 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 list users in your Cortex workspace along with their profile metadata, and to retrieve their role assignments.

### 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 users

> Returns every user in your Cortex tenant along with their profile metadata: name, email, join date, and last active timestamp. Intended for access reviews, compliance, and auditing. Role assignments are available from the separate GET /api/v1/users/roles endpoint. 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 <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"UsersResponse":{"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":"Users for the current page","items":{"$ref":"#/components/schemas/User1"}}}},"User1":{"required":["email","joinedAt","name"],"type":"object","properties":{"email":{"type":"string","description":"Email address of the user"},"joinedAt":{"type":"string","description":"When the user was first added to Cortex (join date), as a UTC ISO-8601 instant","format":"date-time"},"lastActiveAt":{"type":"string","description":"Last time the user logged in, as a UTC ISO-8601 instant; null if the user has never logged in","format":"date-time"},"name":{"type":"string","description":"Display name of the user"}},"description":"Users for the current page"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"errorCode":{"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":{"get":{"description":"Returns every user in your Cortex tenant along with their profile metadata: name, email, join date, and last active timestamp. Intended for access reviews, compliance, and auditing. Role assignments are available from the separate GET /api/v1/users/roles endpoint. Requires the View Roles permission; assign it to a custom role to issue a least-privilege API key for automated reporting.","operationId":"getUsers","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/UsersResponse"}}},"description":"Successfully retrieved users"},"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 users","tags":["Users"]}}}}
```

## 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 <token>` header, where `<token>` 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"},"errorCode":{"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"]}}}}
```