APIs / Clerk

Clerk API changes

Breaking changes, deprecations and new fields in the Clerk API, as they ship.

ClerkClerk Backend API (2026-05-12)2026-10-16 · ddf3c6f81 breaking1 behavioral8 additive

Breakingdirection flip: their tools call this safe
specter_enabled is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
PATCH /instance/protect · specter_enabled
Code that breaks
```
await client.post("/instance/protect", {
  // specter_enabled is now ignored, not rejected
  specter_enabled: value,
});
```
Behavioral
429 is now documented on /email_addresses/{email_address_id}/prepare_verification
An unhandled branch in your error handling.
POST /email_addresses/{email_address_id}/prepare_verification
Additive
Response field act added
No action needed unless you validate responses against a closed schema.
POST /oauth_applications/access_tokens/verify · act

7 new request properties

adopt_audience_resource
audience_uri
token_exchange_enabled
aud_claim_refresh_backfill_enabled
dynamic_client_allowed_scopes
self_serve_directory_sync_enabled
second_factor_verification

ClerkClerk Backend API (2026-05-12)2026-10-02 · f10fb1791 behavioral7 additive

Behavioral
403 is now documented on /beta_features/domain
An unhandled branch in your error handling.
PUT /beta_features/domain · 4 call sites
Additive
/invitations/{invitation_id} added
No action needed.
/invitations/{invitation_id}
Additive
/sso_bypass_allowlist_users added
No action needed.
/sso_bypass_allowlist_users
Additive
/sso_bypass_allowlist_users/{userID} added
No action needed.
/sso_bypass_allowlist_users/{userID}

4 new request properties

saml.idp_certificates
idp_certificates
timezone
reassignment_mappings

ClerkClerk Backend API (2026-05-12)2026-09-22 · 7fcc98742 behavioral3 additive

Behavioral
422 is now documented on /phone_numbers/{phone_number_id}/attempt_verification
An unhandled branch in your error handling.
POST /phone_numbers/{phone_number_id}/attempt_verification
Behavioral
429 is now documented on /phone_numbers/{phone_number_id}/attempt_verification
POST /phone_numbers/{phone_number_id}/attempt_verification
Additive
Value restriction lifted
A relaxation, not a break. Everything you could send before still works, and more is accepted now.
POST /domains · is_satellite
Additive
/sessions/{session_id}/reverifications/{reverification_id} added
No action needed.
/sessions/{session_id}/reverifications/{reverification_id}
Additive
Response field aud added
No action needed unless you validate responses against a closed schema.
POST /oauth_applications/access_tokens/verify · aud

ClerkClerk Backend API (2026-05-12)2026-09-09 · 5db398382 deprecation2 behavioral10 additive

Deprecation
DELETE /users/{user_id}/trusted_devices/{trusted_device_id} deprecated
Still works today. This is the earliest warning you will get before it is removed.
DELETE /users/{user_id}/trusted_devices/{trusted_device_id}
Deprecation
GET /users/{user_id}/trusted_devices deprecated
Still works today. This is the earliest warning you will get before it is removed.
GET /users/{user_id}/trusted_devices
Behavioral
422 is now documented on /directories/{directory_id}/rotate_api_key
An unhandled branch in your error handling.
POST /directories/{directory_id}/rotate_api_key · 2 call sites
Behavioral
403 is now documented on /actor_tokens
An unhandled branch in your error handling.
POST /actor_tokens
Additive
/users/{user_id}/biometric_credentials added
No action needed.
/users/{user_id}/biometric_credentials
Additive
/users/{user_id}/biometric_credentials/{biometric_credential_id} added
No action needed.
/users/{user_id}/biometric_credentials/{biometric_credential_id}
Additive
Request field now accepts null
A relaxation. Existing payloads are unaffected.
PATCH /instance · allowed_origins

7 new request properties

device_authorization_grant_enabled
allowed_subdomains
subdomain_allowlist_enabled
aud_claim_enabled
self_serve_sso_enabled
pkce_required
skip_restriction_checks

ClerkClerk Backend API (2026-05-12)2026-08-14 · 81dd1c542 additive

Additive
/billing/subscription_items/{subscription_item_id}/discounts added
No action needed.
/billing/subscription_items/{subscription_item_id}/discounts
Additive
/billing/subscription_items/{subscription_item_id}/discounts/{discount_id} added
No action needed.
/billing/subscription_items/{subscription_item_id}/discounts/{discount_id}

ClerkClerk Backend API (2026-05-12)2026-08-12 · 7d9ea9b17 additive

Additive
/directories added
No action needed.
/directories
Additive
starting_after is now optional
No action needed.
GET /users · starting_after
Additive
/directories/{directory_id}/rotate_api_key added
No action needed.
/directories/{directory_id}/rotate_api_key
Additive
/directories/{directory_id} added
No action needed.
/directories/{directory_id}
Additive
/directories/{directory_id}/group_role_mappings added
No action needed.
/directories/{directory_id}/group_role_mappings
Additive
/directories/{directory_id}/group_role_mappings/{mapping_id} added
No action needed.
/directories/{directory_id}/group_role_mappings/{mapping_id}
Additive
Request property directory_path added
No action needed unless it is required.
POST /enterprise_connections · custom_attributes[].directory_path · 2 call sites

ClerkClerk Backend API (2026-05-12)2026-08-03 · d46f61343 additive

Additive
/users/{user_id}/remove_password added
No action needed.
/users/{user_id}/remove_password
Additive
/users/{user_id}/trusted_devices added
No action needed.
/users/{user_id}/trusted_devices
Additive
/users/{user_id}/trusted_devices/{trusted_device_id} added
No action needed.
/users/{user_id}/trusted_devices/{trusted_device_id}

ClerkClerk Backend API (2026-05-12)2026-07-30 · 8e1964133 behavioral8 additive

Behavioral
423 is now documented on /templates/{template_type}/{slug}
An unhandled branch in your error handling.
PUT /templates/{template_type}/{slug} · 2 call sites
Behavioral
429 is now documented on /templates/{template_type}/{slug}
PUT /templates/{template_type}/{slug} · 2 call sites
Behavioral
403 is now documented on /sign_in_tokens
An unhandled branch in your error handling.
POST /sign_in_tokens

8 new request properties

notify_primary_email_address_changed
saml.login_hint
login_hint
client_id_metadata_documents_advertised
client_id_metadata_documents_block_implicitly_allowed_clients
client_id_metadata_documents_only_allow_pre_registered_clients
default_scopes
org_id

ClerkClerk Backend API (2026-05-12)2026-07-07 · fd0ea0998 additive

Additive
POST /scim_directories/{scim_directory_id}/group_role_mappings added
No action needed.
POST /scim_directories/{scim_directory_id}/group_role_mappings
Additive
/scim_directories/{scim_directory_id}/rotate_api_key added
No action needed.
/scim_directories/{scim_directory_id}/rotate_api_key
Additive
PUT /scim_directories/{scim_directory_id}/group_role_mappings added
No action needed.
PUT /scim_directories/{scim_directory_id}/group_role_mappings
Additive
GET /scim_directories added
No action needed.
GET /scim_directories
Additive
POST /scim_directories added
No action needed.
POST /scim_directories
Additive
GET /scim_directories/{scim_directory_id} added
No action needed.
GET /scim_directories/{scim_directory_id}
Additive
DELETE /scim_directories/{scim_directory_id} added
No action needed.
DELETE /scim_directories/{scim_directory_id}
Additive
PATCH /scim_directories/{scim_directory_id} added
No action needed.
PATCH /scim_directories/{scim_directory_id}

ClerkClerk Backend API (2026-05-12)2026-07-06 · ebe8d9d62 additive

Additive
DELETE /scim_directories/{scim_directory_id}/group_role_mappings/{mapping_id} added
No action needed.
DELETE /scim_directories/{scim_directory_id}/group_role_mappings/{mapping_id}
Additive
GET /scim_directories/{scim_directory_id}/group_role_mappings added
No action needed.
GET /scim_directories/{scim_directory_id}/group_role_mappings

ClerkClerk Backend API (2026-05-12)2026-07-01 · f11647422 additive

Additive
/scim_directories/{scim_directory_id}/group_role_mappings added
No action needed.
/scim_directories/{scim_directory_id}/group_role_mappings
Additive
/scim_directories/{scim_directory_id}/group_role_mappings/{mapping_id} added
No action needed.
/scim_directories/{scim_directory_id}/group_role_mappings/{mapping_id}

ClerkClerk Backend API (2026-05-12)2026-06-29 · a7f44c771 additive

Additive
/oauth_applications/{oauth_application_id}/revoke_token added
No action needed.
/oauth_applications/{oauth_application_id}/revoke_token

ClerkClerk Backend API (2026-05-12)2026-06-16 · 1b1ad76e1 behavioral

Behavioral
403 is now documented on /organizations/{organization_id}/domains/{domain_id}
An unhandled branch in your error handling.
DELETE /organizations/{organization_id}/domains/{domain_id} · 2 call sites

ClerkClerk Backend API (2026-05-12)2026-06-11 · f631bba92 breaking1 additive

Breakingdirection flip: their tools call this safe
private_metadata is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
PATCH /organizations/{organization_id} · private_metadata
Code that breaks
```
await client.post("/organizations/{organization_id}", {
  // private_metadata is now ignored, not rejected
  private_metadata: value,
});
```
Breakingdirection flip: their tools call this safe
public_metadata is no longer accepted
Usually ignored rather than rejected, so the call succeeds and does something subtly different.
PATCH /organizations/{organization_id} · public_metadata
Code that breaks
```
await client.post("/organizations/{organization_id}", {
  // public_metadata is now ignored, not rejected
  public_metadata: value,
});
```
Additive
PUT /organizations/{organization_id}/metadata added
No action needed.
PUT /organizations/{organization_id}/metadata

ClerkClerk Backend API (2026-05-12)2026-06-08 · 6a9744ab1 additive

Additive
Request property multi_valued added
No action needed unless it is required.
POST /enterprise_connections · custom_attributes[].multi_valued · 2 call sites

ClerkClerk Backend API (2026-05-12)2026-06-04 · fa72ffdf3 breaking1 behavioral9 additive

Breakingdirection flip: their tools call this safe
application_name is no longer accepted
No error is raised. The value is ignored and your results change silently, which is the hardest class of break to notice.
GET /public/interstitial · application_name
Code that breaks
```
await client.post("/public/interstitial", {
  // application_name is now ignored, not rejected
  application_name: value,
});
```
Breakingdirection flip: their tools call this safe
flow is no longer accepted
No error is raised. The value is ignored and your results change silently, which is the hardest class of break to notice.
GET /public/interstitial · flow
Code that breaks
```
await client.post("/public/interstitial", {
  // flow is now ignored, not rejected
  flow: value,
});
```
Breakingdirection flip: their tools call this safe
logo_url is no longer accepted
No error is raised. The value is ignored and your results change silently, which is the hardest class of break to notice.
GET /public/interstitial · logo_url
Code that breaks
```
await client.post("/public/interstitial", {
  // logo_url is now ignored, not rejected
  logo_url: value,
});
```
Behavioral
403 is now documented on /instance/organization_settings
An unhandled branch in your error handling.
PATCH /instance/organization_settings
Additive
/email_addresses/{email_address_id}/attempt_verification added
No action needed.
/email_addresses/{email_address_id}/attempt_verification
Additive
/email_addresses/{email_address_id}/prepare_verification added
No action needed.
/email_addresses/{email_address_id}/prepare_verification
Additive
/enterprise_connections/{enterprise_connection_id}/test_runs added
No action needed.
/enterprise_connections/{enterprise_connection_id}/test_runs
Additive
/phone_numbers/{phone_number_id}/attempt_verification added
No action needed.
/phone_numbers/{phone_number_id}/attempt_verification
Additive
/phone_numbers/{phone_number_id}/prepare_verification added
No action needed.
/phone_numbers/{phone_number_id}/prepare_verification

4 new request properties

identification_status
CreateBillingPriceRequest.supported_billing_periods
email_address_identification_status
phone_number_identification_status