Users

This object represents a verified user in your instance.

Available requests

  • GET /v1/users/:id

  • GET /v1/users

  • POST /v1/users

  • PATCH/v1/users/:id

  • POST /v1/users/:id/profile_image

  • DEL /v1/users/:id

  • GET /v1/users/:id/oauth_access_token/

Example user schema

{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user",
"username": null,
"first_name": "Boss",
"last_name": "Clerk",
"profile_image_url": "https://images.clerk.services/clerk/default-profile.svg",
"primary_email_address_id": "idn_1oBNgISXFbSf5m0uP2Wl0qWtNGX",
"primary_phone_number_id": null,
"password_enabled": true,
"two_factor_enabled": false,
"email_addresses": [
{
"id": "idn_1oBNgISXFbSf5m0uP2Wl0qWtNGX",
"object": "email_address",
"email_address": "[email protected]",
"verification": {
"status": "verified",
"strategy": "email_code",
"attempts": 1,
"expire_at": 1612756733
},
"linked_to": []
}
],
"phone_numbers": [
{
"id": "idn_1q8Uq8Mc4t7WWMy9Z6Og0gNJVui",
"object": "phone_number",
"phone_number": "+15555555555",
"reserved_for_second_factor": false,
"verification": {
"status": "verified",
"strategy": "phone_code",
"attempts": 1,
"expire_at": 1616461499
},
"linked_to": []
}
],
"external_accounts": [],
"public_metadata": {},
"private_metadata": {},
"created_at": 1612756155,
"updated_at": 1612756155
}

get
Retrieve a user

https://api.clerk.dev/v1/users/:id
Retrieve the details of a user.
Request
Response
Request
Headers
Authentication
required
string
Bearer [YOUR_API_KEY]
Response
200: OK
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
}

get
List all users

https://api.clerk.dev/v1/users
List all users. Ordered by creation date, with the newest user first.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Query Parameters
phone_number[]
optional
string
Returns users with the phone numbers specified. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.
email_address[]
optional
string
Returns users with the email addresses specified. Accepts up to 100 email addresses. Any email addresses not found are ignored.
user_id[]
optional
string
Returns users with the user ids specified. Accepts up to 100 user ids. Any user ids not found are ignored.
offset
optional
string
Offset allows pagination through all users. If used, returns users starting after the number supplied.
limit
optional
integer
Puts a limit on the number of users returned. You may return anywhere from 1 to 100 users at a time. Defaults to 10.
Response
200: OK
Cake successfully retrieved.
[
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
},
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
},
]

post
Create a user

https://api.clerk.dev/v1/users
Create a user. Your user management settings determine how you should setup your user model. Any email address and phone number created using this method will be created as verified. Note: If you're performing a migration, checkout our guide on zero downtime migrations
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Form Data Parameters
external_id
optional
string
The ID of the user you use in in your external systems. Must be unique across your instance.
email_address[]
optional
string
Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the users primary email address.
phone_number[]
optional
string
Phone numbers that will be added to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number.
username
optional
string
The username to give to the user. It must be unique across your instance.
password
optional
string
The plaintext password to give the user. Must be at least 8 characters long, and can not be found in any list of hacked passwords.
first_name
optional
string
The first name to give to the user.
last_name
optional
string
The last name to give to the user.
public_metadata
optional
object
Metadata saved on the user, that is visible to both your Frontend and Backend APIs.
private_metadata
optional
string
Metadata saved on the user, that is only visible to your Backend API
unsafe_metadata
optional
string
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
Response
200: OK

patch
Update a user

https://api.clerk.dev/v1/users/:id
Update a user.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Form Data Parameters
public_metadata
optional
object
Metadata saved on the user, that is visible to both your frontend and backend. Note: Object passed in will replace previous value.
private_metadata
optional
object
Metadata saved on the user that is only visible to your backend. Note: Object passed in will replace previous value.
Response
200: OK
// see example schema
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user"
...
}

post
Update a user's profile image

https://clerk.example.com/v1/users/:id/profile_image
Upload a new profile image for a user. Must use multipart/form-data with one image file. It must be a jpg, png, gif, or webp image smaller than 10 MB.
Request
Response
Request
Form Data Parameters
file
required
object
The image to upload.
Response
200: OK

delete
Delete a user

https://api.clerk.dev/v1/users/:id
Delete a user.
Request
Response
Request
Headers
Authorization
required
string
Bearer [YOUR_API_KEY]
Response
200: OK
{
"id": "user_1oBNj55jOjSK9rOYrT5QHqj7eaK",
"object": "user",
"deleted": true
}

get
Retrieve OAuth access token for a user

https://api.clerk.dev/v1/users/:id/oauth_access_tokens/:provider
Retrieve a valid (i.e. non-expired) OAuth access token for a user that has previously authenticated with a particular OAuth provider.
Request
Response
Request
Path Parameters
provider
required
string
The ID of the OAuth provider (e.g. oauth_google).
id
required
string
The user ID.
Response
200: OK
{
"token": "xxxxxxxxxxxxxxxxxxxxx",
"provider": "oauth_google",
"scopes": [
"openid",
"https://www.googleapis.com/auth/userinfo.email"
"https://www.googleapis.com/auth/userinfo.profile"
]
}