List Users
curl --request GET \
--url https://api.example.com/api/v1/entities/users \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/users"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/users"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/users")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "user_abc123",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@company.com",
"profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-15T14:30:00.000Z",
"clerkId": "user_abc123",
"clerkOrgId": "org_xyz789"
},
{
"id": "user_def456",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@company.com",
"profilePictureUrl": null,
"createdAt": "2024-01-12T10:15:00.000Z",
"updatedAt": "2024-01-12T10:15:00.000Z",
"clerkId": "user_def456",
"clerkOrgId": "org_xyz789"
}
]
{
"error": {
"code": "VALIDATION_ERROR",
"message": "User Org Id missing"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
Users
List Users
Retrieves all users in the authenticated user’s organization
GET
/
api
/
v1
/
entities
/
users
List Users
curl --request GET \
--url https://api.example.com/api/v1/entities/users \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.example.com/api/v1/entities/users"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.example.com/api/v1/entities/users', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/entities/users",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/entities/users"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/entities/users")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/entities/users")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body[
{
"id": "user_abc123",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@company.com",
"profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-15T14:30:00.000Z",
"clerkId": "user_abc123",
"clerkOrgId": "org_xyz789"
},
{
"id": "user_def456",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@company.com",
"profilePictureUrl": null,
"createdAt": "2024-01-12T10:15:00.000Z",
"updatedAt": "2024-01-12T10:15:00.000Z",
"clerkId": "user_def456",
"clerkOrgId": "org_xyz789"
}
]
{
"error": {
"code": "VALIDATION_ERROR",
"message": "User Org Id missing"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
Retrieves a list of all users belonging to the currently authenticated user’s organization. This endpoint is useful for displaying team members, assigning leads to users, or managing organization-wide user data.
Authentication
This endpoint requires authentication. The user must be signed in and belong to an organization.Only users within the same Clerk organization are returned. The requesting
user must have a valid organization context.
Request
This endpoint does not require any query parameters or request body.Response
Returns an array of user objects.array
An array of user objects belonging to the organization.
Show User object properties
Show User object properties
string
required
Unique identifier for the user (same as
clerkId).string | null
required
The user’s first name. May be
null if not set in Clerk.string | null
required
The user’s last name. May be
null if not set in Clerk.string | null
required
The user’s primary email address. May be
null if no primary email is set.string | null
required
URL to the user’s profile picture. May be
null if no image is set.string
required
ISO 8601 timestamp of when the user was created.
string
required
ISO 8601 timestamp of when the user was last updated.
string
required
The user’s Clerk ID. This is the same value as
id.string | null
required
The Clerk organization ID the user belongs to.
Response Examples
[
{
"id": "user_abc123",
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@company.com",
"profilePictureUrl": "https://img.clerk.com/user_abc123.jpg",
"createdAt": "2024-01-10T08:00:00.000Z",
"updatedAt": "2024-01-15T14:30:00.000Z",
"clerkId": "user_abc123",
"clerkOrgId": "org_xyz789"
},
{
"id": "user_def456",
"firstName": "Jane",
"lastName": "Doe",
"email": "jane.doe@company.com",
"profilePictureUrl": null,
"createdAt": "2024-01-12T10:15:00.000Z",
"updatedAt": "2024-01-12T10:15:00.000Z",
"clerkId": "user_def456",
"clerkOrgId": "org_xyz789"
}
]
{
"error": {
"code": "VALIDATION_ERROR",
"message": "User Org Id missing"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"message": "User not authenticated"
}
}
Error Codes
| Status Code | Error Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | User does not belong to an organization. Ensure the user has joined an organization in Clerk. |
| 401 | UNAUTHORIZED | User is not authenticated. Ensure a valid session exists. |
| 500 | INTERNAL_ERROR | An unexpected server error occurred. |