{ "opencollection": "1.0.0", "info": { "name": "Clerk Backend API", "version": "2025-11-10" }, "request": { "auth": { "type": "bearer", "token": "{{bearerToken}}" } }, "items": [ { "info": { "name": "Miscellaneous", "type": "folder" }, "items": [ { "info": { "name": "Returns the Markup for the Interstitial Page", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/public/interstitial", "params": [ { "name": "frontendApi", "value": "", "type": "query", "description": "Please use `frontend_api` instead" }, { "name": "frontend_api", "value": "", "type": "query", "description": "The Frontend API key of your instance" }, { "name": "publishable_key", "value": "", "type": "query", "description": "The publishable key of your instance" }, { "name": "proxy_url", "value": "", "type": "query", "description": "The proxy URL of your instance" }, { "name": "domain", "value": "", "type": "query", "description": "The domain of your instance" }, { "name": "sign_in_url", "value": "", "type": "query", "description": "The sign in URL of your instance" }, { "name": "use_domain_for_script", "value": "", "type": "query", "description": "Whether to use the domain for the script URL" } ] }, "docs": "The Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user's authentication state.\nIt is used by Clerk SDKs when the user's authentication state cannot be immediately determined." } ] }, { "info": { "name": "JWKS", "type": "folder" }, "items": [ { "info": { "name": "Retrieve the JSON Web Key Set of the Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/jwks" }, "docs": "Retrieve the JSON Web Key Set of the instance" } ] }, { "info": { "name": "Clients", "type": "folder" }, "items": [ { "info": { "name": "List All Clients", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/clients", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of all clients. The clients are returned sorted by creation date,\nwith the newest clients appearing first.\nWarning: the endpoint is being deprecated and will be removed in future versions." }, { "info": { "name": "Verify a Client", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/clients/verify", "body": { "type": "json", "data": "{}" } }, "docs": "Verifies the client in the provided token" }, { "info": { "name": "Get a Client", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/clients/:client_id", "params": [ { "name": "client_id", "value": "", "type": "path", "description": "Client ID." } ] }, "docs": "Returns the details of a client." } ] }, { "info": { "name": "Email Addresses", "type": "folder" }, "items": [ { "info": { "name": "Create an Email Address", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/email_addresses", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new email address" }, { "info": { "name": "Retrieve an Email Address", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/email_addresses/:email_address_id", "params": [ { "name": "email_address_id", "value": "", "type": "path", "description": "The ID of the email address to retrieve" } ] }, "docs": "Returns the details of an email address." }, { "info": { "name": "Update an Email Address", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/email_addresses/:email_address_id", "params": [ { "name": "email_address_id", "value": "", "type": "path", "description": "The ID of the email address to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an email address." }, { "info": { "name": "Delete an Email Address", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/email_addresses/:email_address_id", "params": [ { "name": "email_address_id", "value": "", "type": "path", "description": "The ID of the email address to delete" } ] }, "docs": "Delete the email address with the given ID" } ] }, { "info": { "name": "Phone Numbers", "type": "folder" }, "items": [ { "info": { "name": "Create a Phone Number", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/phone_numbers", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new phone number" }, { "info": { "name": "Retrieve a Phone Number", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/phone_numbers/:phone_number_id", "params": [ { "name": "phone_number_id", "value": "", "type": "path", "description": "The ID of the phone number to retrieve" } ] }, "docs": "Returns the details of a phone number" }, { "info": { "name": "Update a Phone Number", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/phone_numbers/:phone_number_id", "params": [ { "name": "phone_number_id", "value": "", "type": "path", "description": "The ID of the phone number to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates a phone number" }, { "info": { "name": "Delete a Phone Number", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/phone_numbers/:phone_number_id", "params": [ { "name": "phone_number_id", "value": "", "type": "path", "description": "The ID of the phone number to delete" } ] }, "docs": "Delete the phone number with the given ID" } ] }, { "info": { "name": "Sessions", "type": "folder" }, "items": [ { "info": { "name": "List All Sessions", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/sessions", "params": [ { "name": "client_id", "value": "", "type": "query", "description": "List sessions for the given client" }, { "name": "user_id", "value": "", "type": "query", "description": "List sessions for the given user" }, { "name": "status", "value": "", "type": "query", "description": "Filter sessions by the provided status" }, { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of sessions matching the provided criteria.\nThe sessions are returned sorted by creation date, with the newest sessions appearing first.\n\nNote: This endpoint does not return all sessions that have ever existed. Old and inactive sessions are periodically cleaned up and will not be included in the results.\n\n**Deprecation Notice (2024-01-01):** All parameters were initially considered optional, however\nmoving forward at least one of `client_id` or `user_id` parameters should be provi" }, { "info": { "name": "Create a New Active Session", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sessions", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new active session for the provided user ID.\n\n**This operation is intended only for use in testing, and is not available for production instances.** If you are looking to generate a user session from the backend,\nwe recommend using the [Sign-in Tokens](https://clerk.com/docs/reference/backend-api/tag/Sign-in-Tokens#operation/CreateSignInToken) resource instead." }, { "info": { "name": "Retrieve a Session", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/sessions/:session_id", "params": [ { "name": "session_id", "value": "", "type": "path", "description": "The ID of the session" } ] }, "docs": "Retrieve the details of a session" }, { "info": { "name": "Refresh a Session", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sessions/:session_id/refresh", "params": [ { "name": "session_id", "value": "", "type": "path", "description": "The ID of the session" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Refreshes a session by creating a new session token. A 401 is returned when there\nare validation errors, which signals the SDKs to fall back to the handshake flow." }, { "info": { "name": "Revoke a Session", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sessions/:session_id/revoke", "params": [ { "name": "session_id", "value": "", "type": "path", "description": "The ID of the session" } ] }, "docs": "Sets the status of a session as \"revoked\", which is an unauthenticated state.\nIn multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again." }, { "info": { "name": "Create a Session Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sessions/:session_id/tokens", "params": [ { "name": "session_id", "value": "", "type": "path", "description": "The ID of the session" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a session JSON Web Token (JWT) based on a session." }, { "info": { "name": "Create a Session Token from a JWT Template", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sessions/:session_id/tokens/:template_name", "params": [ { "name": "session_id", "value": "", "type": "path", "description": "The ID of the session" }, { "name": "template_name", "value": "", "type": "path", "description": "The name of the JWT template defined in your instance (e.g. `custom_hasura`)." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a JSON Web Token (JWT) based on a session and a JWT Template name defined for your instance" } ] }, { "info": { "name": "Email & SMS Templates", "type": "folder" }, "items": [ { "info": { "name": "List All Templates", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/templates/:template_type", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of templates to list (email or SMS)" }, { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of all templates.\nThe templates are returned sorted by position." }, { "info": { "name": "Retrieve a Template", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/templates/:template_type/:slug", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of templates to retrieve (email or SMS)" }, { "name": "slug", "value": "", "type": "path", "description": "The slug (i.e. machine-friendly name) of the template to retrieve" } ] }, "docs": "Returns the details of a template" }, { "info": { "name": "Update a Template for a Given Type and Slug", "type": "http" }, "http": { "method": "PUT", "url": "https://api.clerk.com/v1/templates/:template_type/:slug", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of template to update" }, { "name": "slug", "value": "", "type": "path", "description": "The slug of the template to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the existing template of the given type and slug" }, { "info": { "name": "Revert a Template", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/templates/:template_type/:slug/revert", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of template to revert" }, { "name": "slug", "value": "", "type": "path", "description": "The slug of the template to revert" } ] }, "docs": "Reverts an updated template to its default state" }, { "info": { "name": "Preview Changes to a Template", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/templates/:template_type/:slug/preview", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of template to preview" }, { "name": "slug", "value": "", "type": "path", "description": "The slug of the template to preview" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Returns a preview of a template for a given template_type, slug and body" }, { "info": { "name": "Toggle the Delivery by Clerk for a Template of a Given Type and Slug", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/templates/:template_type/:slug/toggle_delivery", "params": [ { "name": "template_type", "value": "", "type": "path", "description": "The type of template to toggle delivery for" }, { "name": "slug", "value": "", "type": "path", "description": "The slug of the template for which to toggle delivery" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Toggles the delivery by Clerk for a template of a given type and slug.\nIf disabled, Clerk will not deliver the resulting email or SMS.\nThe app developer will need to listen to the `email.created` or `sms.created` webhooks in order to handle delivery themselves." } ] }, { "info": { "name": "Users", "type": "folder" }, "items": [ { "info": { "name": "List All Users", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users", "params": [ { "name": "email_address", "value": "", "type": "query", "description": "Returns users with the specified email addresses.\nAccepts up to 100 email addresses.\nAny email addresses not found are ignored." }, { "name": "phone_number", "value": "", "type": "query", "description": "Returns users with the specified phone numbers.\nAccepts up to 100 phone numbers.\nAny phone numbers not found are ignored." }, { "name": "external_id", "value": "", "type": "query", "description": "Returns users with the specified external IDs.\nFor each external ID, the `+` and `-` can be\nprepended to the ID, which denote whether the\nrespective external ID should be included or\nexcluded from the result set.\nAccepts up to 100 external IDs.\nAny external IDs not found are ignored." }, { "name": "username", "value": "", "type": "query", "description": "Returns users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored." }, { "name": "web3_wallet", "value": "", "type": "query", "description": "Returns users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored." }, { "name": "user_id", "value": "", "type": "query", "description": "Returns users with the user IDs specified.\nFor each user ID, the `+` and `-` can be\nprepended to the ID, which denote whether the\nrespective user ID should be included or\nexcluded from the result set.\nAccepts up to 100 user IDs.\nAny user IDs not found are ignored." }, { "name": "organization_id", "value": "", "type": "query", "description": "Returns users that have memberships to the\ngiven organizations.\nFor each organization ID, the `+` and `-` can be\nprepended to the ID, which denote whether the\nrespective organization should be included or\nexcluded from the result set.\nAccepts up to 100 organization IDs." }, { "name": "query", "value": "", "type": "query", "description": "Returns users that match the given query.\nFor possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user IDs, first and last names.\nThe query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well." }, { "name": "email_address_query", "value": "", "type": "query", "description": "Returns users with emails that match the given query, via case-insensitive partial match.\nFor example, `email_address_query=ello` will match a user with the email `HELLO@example.com`." }, { "name": "phone_number_query", "value": "", "type": "query", "description": "Returns users with phone numbers that match the given query, via case-insensitive partial match.\nFor example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`." }, { "name": "username_query", "value": "", "type": "query", "description": "Returns users with usernames that match the given query, via case-insensitive partial match.\nFor example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`." }, { "name": "name_query", "value": "", "type": "query", "description": "Returns users with names that match the given query, via case-insensitive partial match." }, { "name": "banned", "value": "", "type": "query", "description": "Returns users which are either banned (`banned=true`) or not banned (`banned=false`)." }, { "name": "last_active_at_before", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was before the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23." }, { "name": "last_active_at_after", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was after the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23." }, { "name": "last_active_at_since", "value": "1700690400000", "type": "query", "description": "Returns users that had session activity since the given date.\nExample: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.\nDeprecated in favor of `last_active_at_after`." }, { "name": "created_at_before", "value": "1730160000000", "type": "query", "description": "Returns users who have been created before the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created before 2024-10-29." }, { "name": "created_at_after", "value": "1730160000000", "type": "query", "description": "Returns users who have been created after the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created after 2024-10-29." }, { "name": "last_sign_in_at_before", "value": "1700690400000", "type": "query", "description": "Returns users whose last sign-in was before the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last sign-in was before 2023-11-23." }, { "name": "last_sign_in_at_after", "value": "1700690400000", "type": "query", "description": "Returns users whose last sign-in was after the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last sign-in was after 2023-11-23." }, { "name": "provider", "value": "", "type": "query", "description": "Returns users with external accounts for the specified OAuth provider.\nMust be used in combination with the `provider_user_id` parameter.\nFor example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345." }, { "name": "provider_user_id", "value": "", "type": "query", "description": "Returns users with the specified provider user IDs for a specific provider.\nMust be used in combination with the `provider` parameter.\nFor example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345.\nAccepts up to 100 provider user IDs.\nAny provider user IDs not found are ignored." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return users in a particular order.\nAt the moment, you can order the returned users by their `created_at`,`updated_at`,`email_address`,`web3wallet`,`first_name`,`last_name`,`phone_number`,`username`,`last_active_at`,`last_sign_in_at`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example,\nif you pass `order_by=username&order_by=created_at`, we will consider only the first `order_by` parameter, which is `username`. The `created_at` parameter will be ignored in this case." } ] }, "docs": "Returns a list of all users.\nThe users are returned sorted by creation date, with the newest users appearing first." }, { "info": { "name": "Create a New User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new user. Your user management settings determine how you should setup your user model.\n\nAny email address and phone number created using this method will be marked as verified.\n\nNote: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/migrate-overview).\n\nThe following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instance" }, { "info": { "name": "Count Users", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/count", "params": [ { "name": "email_address", "value": "", "type": "query", "description": "Counts users with the specified email addresses.\nAccepts up to 100 email addresses.\nAny email addresses not found are ignored." }, { "name": "phone_number", "value": "", "type": "query", "description": "Counts users with the specified phone numbers.\nAccepts up to 100 phone numbers.\nAny phone numbers not found are ignored." }, { "name": "external_id", "value": "", "type": "query", "description": "Counts users with the specified external IDs.\nAccepts up to 100 external IDs.\nAny external IDs not found are ignored." }, { "name": "username", "value": "", "type": "query", "description": "Counts users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored." }, { "name": "web3_wallet", "value": "", "type": "query", "description": "Counts users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored." }, { "name": "user_id", "value": "", "type": "query", "description": "Counts users with the user IDs specified.\nAccepts up to 100 user IDs.\nAny user IDs not found are ignored." }, { "name": "organization_id", "value": "", "type": "query", "description": "Returns users that have memberships to the given organizations. For each organization ID, the `+` and `-`\ncan be prepended to the ID, which denote whether the respective organization should be included or\nexcluded from the result set. Accepts up to 100 organization IDs." }, { "name": "query", "value": "", "type": "query", "description": "Counts users that match the given query.\nFor possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user IDs, first and last names.\nThe query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well." }, { "name": "email_address_query", "value": "", "type": "query", "description": "Counts users with emails that match the given query, via case-insensitive partial match.\nFor example, `email_address_query=ello` will match a user with the email `HELLO@example.com`,\nand will be included in the resulting count." }, { "name": "phone_number_query", "value": "", "type": "query", "description": "Counts users with phone numbers that match the given query, via case-insensitive partial match.\nFor example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`,\nand will be included in the resulting count." }, { "name": "username_query", "value": "", "type": "query", "description": "Counts users with usernames that match the given query, via case-insensitive partial match.\nFor example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`,\nand will be included in the resulting count." }, { "name": "name_query", "value": "", "type": "query", "description": "Returns users with names that match the given query, via case-insensitive partial match." }, { "name": "banned", "value": "", "type": "query", "description": "Counts users which are either banned (`banned=true`) or not banned (`banned=false`)." }, { "name": "last_active_at_before", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was before the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23." }, { "name": "last_active_at_after", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was after the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23." }, { "name": "last_active_at_since", "value": "1700690400000", "type": "query", "description": "Returns users that had session activity since the given date.\nExample: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.\nDeprecated in favor of `last_active_at_after`." }, { "name": "created_at_before", "value": "1730160000000", "type": "query", "description": "Returns users who have been created before the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created before 2024-10-29." }, { "name": "created_at_after", "value": "1730160000000", "type": "query", "description": "Returns users who have been created after the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created after 2024-10-29." }, { "name": "last_sign_in_at_before", "value": "1700690400000", "type": "query", "description": "Counts users whose last sign-in was before the given date (with millisecond precision).\nExample: use 1700690400000 to count users whose last sign-in was before 2023-11-23." }, { "name": "last_sign_in_at_after", "value": "1700690400000", "type": "query", "description": "Counts users whose last sign-in was after the given date (with millisecond precision).\nExample: use 1700690400000 to count users whose last sign-in was after 2023-11-23." }, { "name": "provider", "value": "", "type": "query", "description": "Counts users with external accounts for the specified OAuth provider.\nMust be used in combination with the `provider_user_id` parameter.\nFor example, use `provider=oauth_google&provider_user_id=12345` to count users with Google provider user ID 12345.\nAccepts up to 100 providers." }, { "name": "provider_user_id", "value": "", "type": "query", "description": "Counts users with the specified provider user IDs for a specific provider.\nMust be used in combination with the `provider` parameter.\nFor example, use `provider=oauth_google&provider_user_id=12345` to count users with Google provider user ID 12345.\nAccepts up to 100 provider user IDs.\nAny provider user IDs not found are ignored." } ] }, "docs": "Returns a total count of all users that match the given filtering criteria." }, { "info": { "name": "Retrieve a User", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to retrieve" } ] }, "docs": "Retrieve the details of a user" }, { "info": { "name": "Update a User", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/users/:user_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update a user's attributes.\n\nYou can set the user's primary contact identifiers (email address and phone numbers) by updating the `primary_email_address_id` and `primary_phone_number_id` attributes respectively.\nBoth IDs should correspond to verified identifications that belong to the user.\n\nYou can remove a user's username by setting the username attribute to null or the blank string \"\".\nThis is a destructive action; the identification will be deleted forever.\nUsernames can be removed only if t" }, { "info": { "name": "Delete a User", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to delete" } ] }, "docs": "Delete the specified user" }, { "info": { "name": "Ban a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/ban", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to ban" } ] }, "docs": "Marks the given user as banned, which means that all their sessions are revoked and they are not allowed to sign in again." }, { "info": { "name": "Unban a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/unban", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to unban" } ] }, "docs": "Removes the ban mark from the given user." }, { "info": { "name": "Ban Multiple Users", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/ban", "body": { "type": "json", "data": "{}" } }, "docs": "Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again." }, { "info": { "name": "Unban Multiple Users", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/unban", "body": { "type": "json", "data": "{}" } }, "docs": "Removes the ban mark from multiple users." }, { "info": { "name": "Lock a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/lock", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to lock" } ] }, "docs": "Marks the given user as locked, which means they are not allowed to sign in again until the lock expires.\nLock duration can be configured in the instance's restrictions settings." }, { "info": { "name": "Unlock a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/unlock", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to unlock" } ] }, "docs": "Removes the lock from the given user." }, { "info": { "name": "Set User Profile Image", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/profile_image", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to update the profile image for" } ], "body": { "type": "multipart-form", "data": [ { "name": "file", "type": "text", "value": "" } ] } }, "docs": "Update a user's profile image" }, { "info": { "name": "Delete User Profile Image", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/profile_image", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to delete the profile image for" } ] }, "docs": "Delete a user's profile image" }, { "info": { "name": "Merge and Update a User's Metadata", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/users/:user_id/metadata", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose metadata will be updated and merged" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update a user's metadata attributes by merging existing values with the provided parameters.\n\nThis endpoint behaves differently than the *Update a user* endpoint.\nMetadata values will not be replaced entirely.\nInstead, a deep merge will be performed.\nDeep means that any nested JSON objects will be merged as well.\n\nYou can remove metadata keys at any level by setting their value to `null`." }, { "info": { "name": "Retrieve a User's Billing Subscription", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id/billing/subscription", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose subscription to retrieve" } ] }, "docs": "Retrieves the billing subscription for the specified user.\nThis includes subscription details, active plans, billing information, and payment status.\nThe subscription contains subscription items which represent the individual plans the user is subscribed to." }, { "info": { "name": "Retrieve a User's Credit Balance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id/billing/credits", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose credit balance to retrieve" } ] }, "docs": "Retrieves the current credit balance for the specified user.\nCredits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges" }, { "info": { "name": "Adjust a User's Credit Balance", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/billing/credits", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose credit balance to adjust" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Increases or decreases the credit balance for the specified user.\nEach adjustment is recorded as a ledger entry. The idempotency_key parameter\nensures that duplicate requests are safely handled." }, { "info": { "name": "Retrieve the OAuth Access Token of a User", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id/oauth_access_tokens/:provider", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user for which to retrieve the OAuth access token" }, { "name": "provider", "value": "", "type": "path", "description": "The ID of the OAuth provider (e.g. `oauth_google`)" }, { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider.\nFor OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned." }, { "info": { "name": "Retrieve All Memberships for a User", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id/organization_memberships", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose organization memberships we want to retrieve" }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Retrieve a paginated list of the user's organization memberships" }, { "info": { "name": "Retrieve All Invitations for a User", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/users/:user_id/organization_invitations", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose organization invitations we want to retrieve" }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "status", "value": "", "type": "query", "description": "Filter organization invitations based on their status" } ] }, "docs": "Retrieve a paginated list of the user's organization invitations" }, { "info": { "name": "Verify the Password of a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/verify_password", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user for whom to verify the password" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Check that the user's password matches the supplied input.\nUseful for custom auth flows and re-verification." }, { "info": { "name": "Verify a TOTP or Backup Code for a User", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/verify_totp", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user for whom to verify the TOTP" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Verify that the provided TOTP or backup code is valid for the user.\nVerifying a backup code will result it in being consumed (i.e. it will\nbecome invalid).\nUseful for custom auth flows and re-verification." }, { "info": { "name": "Disable a User's MFA Methods", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/mfa", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose MFA methods are to be disabled" } ] }, "docs": "Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once." }, { "info": { "name": "Disable All User's Backup Codes", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/backup_code", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose backup codes are to be deleted." } ] }, "docs": "Disable all of a user's backup codes." }, { "info": { "name": "Delete a User Passkey", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/passkeys/:passkey_identification_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user that owns the passkey identity" }, { "name": "passkey_identification_id", "value": "", "type": "path", "description": "The ID of the passkey identity to be deleted" } ] }, "docs": "Delete the passkey identification for a given user and notify them through email." }, { "info": { "name": "Delete a User Web3 Wallet", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/web3_wallets/:web3_wallet_identification_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user that owns the web3 wallet" }, { "name": "web3_wallet_identification_id", "value": "", "type": "path", "description": "The ID of the web3 wallet identity to be deleted" } ] }, "docs": "Delete the web3 wallet identification for a given user." }, { "info": { "name": "Delete All the User's TOTPs", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/totp", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user whose TOTPs are to be deleted" } ] }, "docs": "Deletes all of the user's TOTPs." }, { "info": { "name": "Delete External Account", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/users/:user_id/external_accounts/:external_account_id", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user's external account" }, { "name": "external_account_id", "value": "", "type": "path", "description": "The ID of the external account to delete" } ] }, "docs": "Delete an external account by ID." }, { "info": { "name": "Set a User's Password as Compromised", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/password/set_compromised", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to set the password as compromised" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Sets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in." }, { "info": { "name": "Unset a User's Password as Compromised", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/users/:user_id/password/unset_compromised", "params": [ { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to unset the compromised status for" } ] }, "docs": "Sets the given user's password as no longer compromised. The user will no longer be prompted to reset their password on their next sign-in." } ] }, { "info": { "name": "Invitations", "type": "folder" }, "items": [ { "info": { "name": "List All Invitations", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/invitations", "params": [ { "name": "status", "value": "", "type": "query", "description": "Filter invitations based on their status" }, { "name": "query", "value": "", "type": "query", "description": "Filter invitations based on their `email_address` or `id`" }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return invitations in a particular order.\nAt the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns all non-revoked invitations for your application, sorted by creation date" }, { "info": { "name": "Create an Invitation", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/invitations", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new invitation for the given email address and sends the invitation email.\nKeep in mind that you cannot create an invitation if there is already one for the given email address.\nAlso, trying to create an invitation for an email address that already exists in your application will result to an error." }, { "info": { "name": "Create Multiple Invitations", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/invitations/bulk", "body": { "type": "json", "data": "{}" } }, "docs": "Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the\ninvitations as emails by setting the `notify` parameter to `true`. There cannot be an existing invitation for any\nof the email addresses you provide unless you set `ignore_existing` to `true` for specific email addresses. Please\nnote that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed.\n\nThis endpoint is limited to a maximu" }, { "info": { "name": "Revokes an Invitation", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/invitations/:invitation_id/revoke", "params": [ { "name": "invitation_id", "value": "", "type": "path", "description": "The ID of the invitation to be revoked" } ] }, "docs": "Revokes the given invitation.\nRevoking an invitation will prevent the user from using the invitation link that was sent to them.\nHowever, it doesn't prevent the user from signing up if they follow the sign up flow.\nOnly active (i.e. non-revoked) invitations can be revoked." } ] }, { "info": { "name": "Organization Invitations", "type": "folder" }, "items": [ { "info": { "name": "Get a List of Organization Invitations for the Current Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_invitations", "params": [ { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organization invitations in a particular order.\nAt the moment, you can order the returned organization invitations either by their `created_at` or `email_address`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "status", "value": "", "type": "query", "description": "Filter organization invitations based on their status" }, { "name": "query", "value": "", "type": "query", "description": "Filter organization invitations based on their `email_address`" }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "This request returns the list of organization invitations for the instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nYou can filter them by providing the 'status' query parameter, that accepts multiple values.\nYou can change the order by providing the 'order' query parameter, that accepts multiple values.\nYou can filter by the invited user email address providing the `query` query parameter.\nThe organization invitations are ordered by descending creation" }, { "info": { "name": "Get a List of Organization Invitations", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "status", "value": "", "type": "query", "description": "Filter organization invitations based on their status" }, { "name": "email_address", "value": "", "type": "query", "description": "Returns organization invitations inviting the specified email address." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organization invitations in a particular order.\nYou can order the returned organization invitations either by their `created_at` or `email_address`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "This request returns the list of organization invitations.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nYou can filter them by providing the 'status' query parameter, that accepts multiple values.\nThe organization invitations are ordered by descending creation date.\nMost recent invitations will be returned first.\nAny invitations created as a result of an Organization Domain are not included in the results." }, { "info": { "name": "Create and Send an Organization Invitation", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization for which to send the invitation" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new organization invitation and sends an email to the provided `email_address` with a link to accept the invitation and join the organization.\nYou can specify the `role` for the invited organization member.\n\nNew organization invitations get a \"pending\" status until they are revoked by an organization administrator or accepted by the invitee.\n\nThe request body supports passing an optional `redirect_url` parameter.\nWhen the invited user clicks the link to accept the invitation, they will" }, { "info": { "name": "Bulk Create and Send Organization Invitations", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations/bulk", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization.\n\nThis endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.\n\nYou can specify a different `role` for each invited organization member.\nNew organization invitations get a \"pending\" status until they are revoked by an organization administrator or accepted by t" }, { "info": { "name": "Get a List of Pending Organization Invitations", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations/pending", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "This request returns the list of organization invitations with \"pending\" status.\nThese are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe organization invitations are ordered by descending creation date.\nMost recent invitations will be returned first.\nAny invitations created as a result of an Organization Domain are not included" }, { "info": { "name": "Retrieve an Organization Invitation by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations/:invitation_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "invitation_id", "value": "", "type": "path", "description": "The organization invitation ID." } ] }, "docs": "Use this request to get an existing organization invitation by ID." }, { "info": { "name": "Revoke a Pending Organization Invitation", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/invitations/:invitation_id/revoke", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "invitation_id", "value": "", "type": "path", "description": "The organization invitation ID." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Use this request to revoke a previously issued organization invitation.\nRevoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation.\nOnly organization invitations with \"pending\" status can be revoked.\nThe request accepts the `requesting_user_id` parameter to specify the user which revokes the invitation.\nOnly users with \"admin\" role can revoke invitations." } ] }, { "info": { "name": "Allow-list / Block-list", "type": "folder" }, "items": [ { "info": { "name": "List All Identifiers on the Allow-list", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/allowlist_identifiers", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Get a list of all identifiers allowed to sign up to an instance" }, { "info": { "name": "Add Identifier to the Allow-list", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/allowlist_identifiers", "body": { "type": "json", "data": "{}" } }, "docs": "Create an identifier allowed to sign up to an instance" }, { "info": { "name": "Delete Identifier from Allow-list", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/allowlist_identifiers/:identifier_id", "params": [ { "name": "identifier_id", "value": "", "type": "path", "description": "The ID of the identifier to delete from the allow-list" } ] }, "docs": "Delete an identifier from the instance allow-list" }, { "info": { "name": "List All Identifiers on the Block-list", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/blocklist_identifiers" }, "docs": "Get a list of all identifiers which are not allowed to access an instance" }, { "info": { "name": "Add Identifier to the Block-list", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/blocklist_identifiers", "body": { "type": "json", "data": "{}" } }, "docs": "Create an identifier that is blocked from accessing an instance" }, { "info": { "name": "Delete Identifier from Block-list", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/blocklist_identifiers/:identifier_id", "params": [ { "name": "identifier_id", "value": "", "type": "path", "description": "The ID of the identifier to delete from the block-list" } ] }, "docs": "Delete an identifier from the instance block-list" } ] }, { "info": { "name": "Beta Features", "type": "folder" }, "items": [ { "info": { "name": "Update Instance Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/beta_features/instance_settings", "body": { "type": "json", "data": "{}" } }, "docs": "Updates the settings of an instance" }, { "info": { "name": "Update Production Instance Domain", "type": "http" }, "http": { "method": "PUT", "url": "https://api.clerk.com/v1/beta_features/domain", "body": { "type": "json", "data": "{}" } }, "docs": "Change the domain of a production instance.\n\nChanging the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy-certificates), updating your Social Connection's redirect URLs and setting the new keys in your code.\n\nWARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being" }, { "info": { "name": "Update Production Instance Domain", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/instance/change_domain", "body": { "type": "json", "data": "{}" } }, "docs": "Change the domain of a production instance.\n\nChanging the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy-certificates), updating your Social Connection's redirect URLs and setting the new keys in your code.\n\nWARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being" } ] }, { "info": { "name": "Actor Tokens", "type": "folder" }, "items": [ { "info": { "name": "Create Actor Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/actor_tokens", "body": { "type": "json", "data": "{}" } }, "docs": "Create an actor token that can be used to impersonate the given user.\nThe `actor` parameter needs to include at least a \"sub\" key whose value is the ID of the actor (impersonating) user." }, { "info": { "name": "Revoke Actor Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/actor_tokens/:actor_token_id/revoke", "params": [ { "name": "actor_token_id", "value": "", "type": "path", "description": "The ID of the actor token to be revoked." } ] }, "docs": "Revokes a pending actor token." } ] }, { "info": { "name": "Domains", "type": "folder" }, "items": [ { "info": { "name": "List All Instance Domains", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/domains" }, "docs": "Use this endpoint to get a list of all domains for an instance.\nThe response will contain the primary domain for the instance and any satellite domains. Each domain in the response contains information about the URLs where Clerk operates and the required CNAME targets." }, { "info": { "name": "Add a Domain", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/domains", "body": { "type": "json", "data": "{}" } }, "docs": "Add a new domain for your instance.\nUseful in the case of multi-domain instances, allows adding satellite domains to an instance.\nThe new domain must have a `name`. The domain name can contain the port for development instances, like `localhost:3000`.\nAt the moment, instances can have only one primary domain, so the `is_satellite` parameter must be set to `true`.\nIf you're planning to configure the new satellite domain to run behind a proxy, pass the `proxy_url` parameter accordingly." }, { "info": { "name": "Update a Domain", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/domains/:domain_id", "params": [ { "name": "domain_id", "value": "", "type": "path", "description": "The ID of the domain that will be updated." } ], "body": { "type": "json", "data": "{}" } }, "docs": "The `proxy_url` can be updated only for production instances.\nUpdate one of the instance's domains. Both primary and satellite domains can be updated.\nIf you choose to use Clerk via proxy, use this endpoint to specify the `proxy_url`.\nWhenever you decide you'd rather switch to DNS setup for Clerk, simply set `proxy_url`\nto `null` for the domain. When you update a production instance's primary domain name,\nyou have to make sure that you've completed all the necessary setup steps for DNS and\nemail" }, { "info": { "name": "Delete a Satellite Domain", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/domains/:domain_id", "params": [ { "name": "domain_id", "value": "", "type": "path", "description": "The ID of the domain that will be deleted. Must be a satellite domain." } ] }, "docs": "Deletes a satellite domain for the instance.\nIt is currently not possible to delete the instance's primary domain." } ] }, { "info": { "name": "Instance Settings", "type": "folder" }, "items": [ { "info": { "name": "Fetch the Current Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/instance" }, "docs": "Fetches the current instance" }, { "info": { "name": "Update Instance Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance", "body": { "type": "json", "data": "{}" } }, "docs": "Updates the settings of an instance" }, { "info": { "name": "Update Instance Restrictions", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance/restrictions", "body": { "type": "json", "data": "{}" } }, "docs": "Updates the restriction settings of an instance" }, { "info": { "name": "Get Instance Protect Settings", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/instance/protect" }, "docs": "Get Instance Protect Settings" }, { "info": { "name": "Update Instance Protect Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance/protect", "body": { "type": "json", "data": "{}" } }, "docs": "Update Instance Protect Settings" }, { "info": { "name": "Get Instance Communication Settings", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/instance/communication" }, "docs": "Retrieves the per-instance SMS communication settings, including the SMS country blocklist." }, { "info": { "name": "Update Instance Communication Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance/communication", "body": { "type": "json", "data": "{}" } }, "docs": "Replaces the SMS country blocklist for this instance. Pass the full set of ISO 3166-1\nalpha-2 country codes that should be blocked; codes that aren't recognized as SMS-tier\ncountries are silently dropped from the persisted list. Omitting `blocked_country_codes`\nis a no-op.\n" }, { "info": { "name": "Get OAuth Application Settings", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/instance/oauth_application_settings" }, "docs": "Retrieves the settings for OAuth applications for the instance (dynamic client registration, JWT access tokens, etc.)." }, { "info": { "name": "Update OAuth Application Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance/oauth_application_settings", "body": { "type": "json", "data": "{}" } }, "docs": "Updates the OAuth application settings for the instance." }, { "info": { "name": "Get Instance Organization Settings", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/instance/organization_settings" }, "docs": "Retrieves the organization settings of the instance" }, { "info": { "name": "Update Instance Organization Settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/instance/organization_settings", "body": { "type": "json", "data": "{}" } }, "docs": "Updates the organization settings of the instance" } ] }, { "info": { "name": "Webhooks", "type": "folder" }, "items": [ { "info": { "name": "Create a Svix App", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/webhooks/svix" }, "docs": "Create a Svix app and associate it with the current instance" }, { "info": { "name": "Delete a Svix App", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/webhooks/svix" }, "docs": "Delete a Svix app and disassociate it from the current instance" }, { "info": { "name": "Create a Svix Dashboard URL", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/webhooks/svix_url" }, "docs": "Generate a new URL for accessing the Svix's management dashboard for that particular instance" } ] }, { "info": { "name": "JWT Templates", "type": "folder" }, "items": [ { "info": { "name": "List All Templates", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/jwt_templates", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "List All Templates" }, { "info": { "name": "Create a JWT Template", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/jwt_templates", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new JWT template" }, { "info": { "name": "Retrieve a Template", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/jwt_templates/:template_id", "params": [ { "name": "template_id", "value": "", "type": "path", "description": "JWT Template ID" } ] }, "docs": "Retrieve the details of a given JWT template" }, { "info": { "name": "Update a JWT Template", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/jwt_templates/:template_id", "params": [ { "name": "template_id", "value": "", "type": "path", "description": "The ID of the JWT template to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing JWT template" }, { "info": { "name": "Delete a Template", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/jwt_templates/:template_id", "params": [ { "name": "template_id", "value": "", "type": "path", "description": "JWT Template ID" } ] }, "docs": "Delete a Template" } ] }, { "info": { "name": "Machines", "type": "folder" }, "items": [ { "info": { "name": "Get a List of Machines for an Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/machines", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "query", "value": "", "type": "query", "description": "Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return machines in a particular order.\nYou can order the returned machines by their `name` or `created_at`.\nTo specify the direction, use the `+` or `-` symbols prepended to the property to order by.\nFor example, to return machines in descending order by `created_at`, use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." } ] }, "docs": "This request returns the list of machines for an instance. The machines are\nordered by descending creation date (i.e. most recent machines will be\nreturned first)" }, { "info": { "name": "Create a Machine", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/machines", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new machine." }, { "info": { "name": "Retrieve a Machine", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/machines/:machine_id", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine to retrieve" } ] }, "docs": "Returns the details of a machine." }, { "info": { "name": "Update a Machine", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/machines/:machine_id", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing machine.\nOnly the provided fields will be updated." }, { "info": { "name": "Delete a Machine", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/machines/:machine_id", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine to delete" } ] }, "docs": "Deletes a machine." }, { "info": { "name": "Retrieve a Machine Secret Key", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/machines/:machine_id/secret_key", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine to retrieve the secret key for" } ] }, "docs": "Returns the secret key for a machine." }, { "info": { "name": "Rotate a Machine's Secret Key", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/machines/:machine_id/secret_key/rotate", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine to rotate the secret key for" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Rotates the machine's secret key.\nWhen the secret key is rotated, make sure to update it in your machine/application.\nThe previous secret key will remain valid for the duration specified by the previous_token_ttl parameter." }, { "info": { "name": "Create a Machine Scope", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/machines/:machine_id/scopes", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine that will have access to another machine" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new machine scope, allowing the specified machine to access another machine.\nMaximum of 150 scopes per machine." }, { "info": { "name": "Delete a Machine Scope", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/machines/:machine_id/scopes/:other_machine_id", "params": [ { "name": "machine_id", "value": "", "type": "path", "description": "The ID of the machine that has access to another machine" }, { "name": "other_machine_id", "value": "", "type": "path", "description": "The ID of the machine that is being accessed" } ] }, "docs": "Deletes a machine scope, removing access from one machine to another." } ] }, { "info": { "name": "Organizations", "type": "folder" }, "items": [ { "info": { "name": "Get a List of Organizations for an Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations", "params": [ { "name": "include_members_count", "value": "", "type": "query", "description": "Flag to denote whether the member counts of each organization should be included in the response or not." }, { "name": "include_missing_member_with_elevated_permissions", "value": "", "type": "query", "description": "Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization." }, { "name": "query", "value": "", "type": "query", "description": "Returns organizations with ID, name, or slug that match the given query.\nUses exact match for organization ID and partial match for name and slug." }, { "name": "user_id", "value": "", "type": "query", "description": "Returns organizations that include any of the specified user IDs as members. Any user IDs not found are ignored.\nFor each user ID, the `+` and `-` can be prepended to the ID, which denote whether the\nrespective organization should be included or excluded from the result set." }, { "name": "organization_id", "value": "", "type": "query", "description": "Returns organizations with the organization IDs specified. Any organization IDs not found are ignored.\nFor each organization ID, the `+` and `-` can be prepended to the ID, which denote whether the\nrespective organization should be included or excluded from the result set. Accepts up to 100 organization IDs.\nExample: ?organization_id=+org_1&organization_id=-org_2" }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organizations in a particular order.\nAt the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "This request returns the list of organizations for an instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe organizations are ordered by descending creation date.\nMost recent organizations will be returned first." }, { "info": { "name": "Create an Organization", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new organization with the given name for an instance.\nYou can specify an optional slug for the new organization.\nIf provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash \"-\".\nOrganization slugs must be unique for the instance.\nYou can provide additional metadata for the organization and set any custom attribute you want.\nOrganizations support private and public metadata.\nPrivate metadata can only be accessed from the Backen" }, { "info": { "name": "Retrieve an Organization by ID or Slug", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID or slug of the organization" }, { "name": "include_members_count", "value": "", "type": "query", "description": "Flag to denote whether or not the organization's members count should be included in the response." }, { "name": "include_missing_member_with_elevated_permissions", "value": "", "type": "query", "description": "Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization." } ] }, "docs": "Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter." }, { "info": { "name": "Update an Organization", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organizations/:organization_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing organization" }, { "info": { "name": "Delete an Organization", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organizations/:organization_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to delete" } ] }, "docs": "Deletes the given organization.\nPlease note that deleting an organization will also delete all memberships and invitations.\nThis is not reversible.\n\nAfter the organization is deleted, any user's active sessions that contain the deleted\norganization will be cleared." }, { "info": { "name": "Merge and Update Metadata for an Organization", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organizations/:organization_id/metadata", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization for which metadata will be merged or updated" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update organization metadata attributes by merging existing values with the provided parameters.\nMetadata values will be updated via a deep merge.\nDeep meaning that any nested JSON objects will be merged as well.\nYou can remove metadata keys at any level by setting their value to `null`." }, { "info": { "name": "Upload a Logo for the Organization", "type": "http" }, "http": { "method": "PUT", "url": "https://api.clerk.com/v1/organizations/:organization_id/logo", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization for which to upload a logo" } ], "body": { "type": "multipart-form", "data": [ { "name": "uploader_user_id", "type": "text", "value": "" }, { "name": "file", "type": "text", "value": "" } ] } }, "docs": "Set or replace an organization's logo, by uploading an image file.\nThis endpoint uses the `multipart/form-data` request content type and accepts a file of image type.\nThe file size cannot exceed 10MB.\nOnly the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`." }, { "info": { "name": "Delete the Organization's Logo.", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organizations/:organization_id/logo", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization for which the logo will be deleted." } ] }, "docs": "Delete the organization's logo." }, { "info": { "name": "Retrieve an Organization's Billing Subscription", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/billing/subscription", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization whose subscription to retrieve" } ] }, "docs": "Retrieves the billing subscription for the specified organization.\nThis includes subscription details, active plans, billing information, and payment status.\nThe subscription contains subscription items which represent the individual plans the organization is subscribed to." }, { "info": { "name": "Retrieve an Organization's Credit Balance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/billing/credits", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization whose credit balance to retrieve" } ] }, "docs": "Retrieves the current credit balance for the specified organization.\nCredits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges." }, { "info": { "name": "Adjust an Organization's Credit Balance", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/billing/credits", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization whose credit balance to adjust" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Increases or decreases the credit balance for the specified organization.\nEach adjustment is recorded as a ledger entry. The idempotency_key parameter\nensures that duplicate requests are safely handled." } ] }, { "info": { "name": "Organization Roles", "type": "folder" }, "items": [ { "info": { "name": "Get a List of Organization Roles", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_roles", "params": [ { "name": "query", "value": "", "type": "query", "description": "Returns organization roles with ID, name, or key that match the given query.\nUses exact match for organization role ID and partial match for name and key." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organization roles in a particular order.\nAt the moment, you can order the returned organization roles by their `created_at`, `name`, or `key`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want organization roles to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "This request returns the list of organization roles for the instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe organization roles are ordered by descending creation date.\nMost recent roles will be returned first." }, { "info": { "name": "Create an Organization Role", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organization_roles", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new organization role with the given name and permissions for an instance.\nThe key must be unique for the instance and start with the 'org:' prefix, followed by lowercase alphanumeric characters and underscores only.\nYou can optionally provide a description for the role and specify whether it should be included in the initial role set.\nOrganization roles support permissions that can be assigned to control access within the organization." }, { "info": { "name": "Retrieve an Organization Role", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_roles/:organization_role_id", "params": [ { "name": "organization_role_id", "value": "", "type": "path", "description": "The ID of the organization role" } ] }, "docs": "Use this request to retrieve an existing organization role by its ID." }, { "info": { "name": "Update an Organization Role", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organization_roles/:organization_role_id", "params": [ { "name": "organization_role_id", "value": "", "type": "path", "description": "The ID of the organization role to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing organization role.\nYou can update the name, key, description, and permissions of the role.\nAll parameters are optional - you can update only the fields you want to change.\nIf the role is used as a creator role or domain default role, updating the key will cascade the update to the organization settings." }, { "info": { "name": "Delete an Organization Role", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organization_roles/:organization_role_id", "params": [ { "name": "organization_role_id", "value": "", "type": "path", "description": "The ID of the organization role to delete" } ] }, "docs": "Deletes the organization role.\nThe role cannot be deleted if it is currently used as the default creator role, domain default role, assigned to any members, or exists in any invitations." }, { "info": { "name": "Assign a Permission to an Organization Role", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organization_roles/:organization_role_id/permissions/:permission_id", "params": [ { "name": "organization_role_id", "value": "", "type": "path", "description": "The ID of the organization role" }, { "name": "permission_id", "value": "", "type": "path", "description": "The ID of the permission to assign" } ] }, "docs": "Assigns a permission to an organization role" }, { "info": { "name": "Remove a Permission from an Organization Role", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organization_roles/:organization_role_id/permissions/:permission_id", "params": [ { "name": "organization_role_id", "value": "", "type": "path", "description": "The ID of the organization role" }, { "name": "permission_id", "value": "", "type": "path", "description": "The ID of the permission to remove" } ] }, "docs": "Removes a permission from an organization role" } ] }, { "info": { "name": "Organization Memberships", "type": "folder" }, "items": [ { "info": { "name": "Get a List of All Members of an Organization", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/memberships", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "order_by", "value": "", "type": "query", "description": "Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.\nBy prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.\"" }, { "name": "user_id", "value": "", "type": "query", "description": "Returns users with the user IDs specified. For each user ID, the `+` and `-` can be\nprepended to the ID, which denote whether the respective user ID should be included or\nexcluded from the result set. Accepts up to 100 user IDs. Any user IDs not found are ignored." }, { "name": "email_address", "value": "", "type": "query", "description": "Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored." }, { "name": "phone_number", "value": "", "type": "query", "description": "Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored." }, { "name": "username", "value": "", "type": "query", "description": "Returns users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored." }, { "name": "web3_wallet", "value": "", "type": "query", "description": "Returns users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored." }, { "name": "role", "value": "", "type": "query", "description": "Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored." }, { "name": "query", "value": "", "type": "query", "description": "Returns users that match the given query.\nFor possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user IDs, first and last names.\nThe query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well." }, { "name": "email_address_query", "value": "", "type": "query", "description": "Returns users with emails that match the given query, via case-insensitive partial match.\nFor example, `email_address_query=ello` will match a user with the email `HELLO@example.com`." }, { "name": "phone_number_query", "value": "", "type": "query", "description": "Returns users with phone numbers that match the given query, via case-insensitive partial match.\nFor example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`." }, { "name": "username_query", "value": "", "type": "query", "description": "Returns users with usernames that match the given query, via case-insensitive partial match.\nFor example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`." }, { "name": "name_query", "value": "", "type": "query", "description": "Returns users with names that match the given query, via case-insensitive partial match." }, { "name": "last_active_at_before", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was before the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23." }, { "name": "last_active_at_after", "value": "1700690400000", "type": "query", "description": "Returns users whose last session activity was after the given date (with millisecond precision).\nExample: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23." }, { "name": "created_at_before", "value": "1730160000000", "type": "query", "description": "Returns users who have been created before the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created before 2024-10-29." }, { "name": "created_at_after", "value": "1730160000000", "type": "query", "description": "Returns users who have been created after the given date (with millisecond precision).\nExample: use 1730160000000 to retrieve users who have been created after 2024-10-29." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Retrieves all user memberships for the given organization" }, { "info": { "name": "Create a New Organization Membership", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/memberships", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization where the new membership will be created" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Adds a user as a member to the given organization.\nOnly users in the same instance as the organization can be added as members.\n\nThis organization will be the user's [active organization] (https://clerk.com/docs/organizations/overview#active-organization)\nthe next time they create a session, presuming they don't explicitly set a\ndifferent organization as active before then." }, { "info": { "name": "Update an Organization Membership", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organizations/:organization_id/memberships/:user_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to which this membership belongs" }, { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to which this membership belongs" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the properties of an existing organization membership" }, { "info": { "name": "Remove a Member from an Organization", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organizations/:organization_id/memberships/:user_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to which this membership belongs" }, { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to which this membership belongs" } ] }, "docs": "Removes the given membership from the organization" }, { "info": { "name": "Merge and Update Organization Membership Metadata", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organizations/:organization_id/memberships/:user_id/metadata", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to which this membership belongs" }, { "name": "user_id", "value": "", "type": "path", "description": "The ID of the user to which this membership belongs" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update an organization membership's metadata attributes by merging existing values with the provided parameters.\nMetadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well.\nYou can remove metadata keys at any level by setting their value to `null`." }, { "info": { "name": "Get a List of All Organization Memberships Within an Instance.", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_memberships", "params": [ { "name": "order_by", "value": "", "type": "query", "description": "Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.\nBy prepending one of those values with + or -,\nwe can choose to sort in ascending (ASC) or descending (DESC) order." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Retrieves all organization user memberships for the given instance." } ] }, { "info": { "name": "Organization Domains", "type": "folder" }, "items": [ { "info": { "name": "Get a List of All Domains of an Organization.", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organizations/:organization_id/domains", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The organization ID." }, { "name": "verified", "value": "", "type": "query", "description": "Filter domains by their verification status. `true` or `false`" }, { "name": "enrollment_mode", "value": "", "type": "query", "description": "Filter domains by their enrollment mode" }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Get a list of all domains of an organization." }, { "info": { "name": "Create a New Organization Domain.", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organizations/:organization_id/domains", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization where the new domain will be created." } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new organization domain. By default the domain is verified, but can be optionally set to unverified." }, { "info": { "name": "Update an Organization Domain.", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organizations/:organization_id/domains/:domain_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to which the domain belongs" }, { "name": "domain_id", "value": "", "type": "path", "description": "The ID of the domain" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the properties of an existing organization domain." }, { "info": { "name": "Remove a Domain from an Organization.", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organizations/:organization_id/domains/:domain_id", "params": [ { "name": "organization_id", "value": "", "type": "path", "description": "The ID of the organization to which the domain belongs" }, { "name": "domain_id", "value": "", "type": "path", "description": "The ID of the domain" } ] }, "docs": "Removes the given domain from the organization." }, { "info": { "name": "List All Organization Domains", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_domains", "params": [ { "name": "organization_id", "value": "", "type": "query", "description": "The ID of the organization to filter domains by" }, { "name": "verified", "value": "", "type": "query", "description": "Filter by verification status" }, { "name": "enrollment_mode", "value": "", "type": "query", "description": "Filter by enrollment mode" }, { "name": "query", "value": "", "type": "query", "description": "Search domains by name or organization ID.\nIf the query starts with \"org_\", it will search by exact organization ID match.\nOtherwise, it performs a case-insensitive partial match on the domain name.\n\nNote: An empty string or whitespace-only value is not allowed and will result in a validation error.\n" }, { "name": "domains", "value": "", "type": "query", "description": "Filter by exact domain names. Accepts multiple values (e.g. domains=example.com&domains=test.org)." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organization domains in a particular order.\nAt the moment, you can order the returned domains by their `name` or `created_at`.\nIn order to specify the direction, you can use the `+/-` symbols prepended to the property to order by.\nFor example, if you want domains to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`.\n" }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." } ] }, "docs": "Retrieves a list of all organization domains within the current instance.\nThis endpoint can be used to list all domains across all organizations\nor filter domains by organization, verification status, enrollment mode, or search query.\n\nThe response includes pagination information and details about each domain\nincluding its verification status, enrollment mode, and associated counts.\n" } ] }, { "info": { "name": "Proxy Checks", "type": "folder" }, "items": [ { "info": { "name": "Verify the Proxy Configuration for Your Domain", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/proxy_checks", "body": { "type": "json", "data": "{}" } }, "docs": "This endpoint can be used to validate that a proxy-enabled domain is operational.\nIt tries to verify that the proxy URL provided in the parameters maps to a functional proxy that can reach the Clerk Frontend API.\n\nYou can use this endpoint before you set a proxy URL for a domain. This way you can ensure that switching to proxy-based\nconfiguration will not lead to downtime for your instance.\n\nThe `proxy_url` parameter allows for testing proxy configurations for domains that don't have a proxy URL" } ] }, { "info": { "name": "Redirect URLs", "type": "folder" }, "items": [ { "info": { "name": "List All Redirect URLs", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/redirect_urls", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Lists all whitelisted redirect_urls for the instance" }, { "info": { "name": "Create a Redirect URL", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/redirect_urls", "body": { "type": "json", "data": "{}" } }, "docs": "Create a redirect URL" }, { "info": { "name": "Retrieve a Redirect URL", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/redirect_urls/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The ID of the redirect URL" } ] }, "docs": "Retrieve the details of the redirect URL with the given ID" }, { "info": { "name": "Delete a Redirect URL", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/redirect_urls/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The ID of the redirect URL" } ] }, "docs": "Remove the selected redirect URL from the whitelist of the instance" } ] }, { "info": { "name": "Sign-in Tokens", "type": "folder" }, "items": [ { "info": { "name": "Create Sign-in Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sign_in_tokens", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new sign-in token and associates it with the given user.\nBy default, sign-in tokens expire in 30 days.\nYou can optionally supply a different duration in seconds using the `expires_in_seconds` property." }, { "info": { "name": "Revoke the Given Sign-in Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/sign_in_tokens/:sign_in_token_id/revoke", "params": [ { "name": "sign_in_token_id", "value": "", "type": "path", "description": "The ID of the sign-in token to be revoked" } ] }, "docs": "Revokes a pending sign-in token" } ] }, { "info": { "name": "Sign Ups", "type": "folder" }, "items": [ { "info": { "name": "Retrieve a Sign-up by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/sign_ups/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The ID of the sign-up to retrieve" } ] }, "docs": "Retrieve the details of the sign-up with the given ID" }, { "info": { "name": "Update a Sign-up", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/sign_ups/:id", "params": [ { "name": "id", "value": "", "type": "path", "description": "The ID of the sign-up to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update the sign-up with the given ID" } ] }, { "info": { "name": "OAuth Applications", "type": "folder" }, "items": [ { "info": { "name": "Get a List of OAuth Applications for an Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/oauth_applications", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return OAuth applications in a particular order.\nAt the moment, you can order the returned OAuth applications by their `created_at` and `name`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example,\nif you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case." }, { "name": "name_query", "value": "", "type": "query", "description": "Returns OAuth applications with names that match the given query, via case-insensitive partial match." } ] }, "docs": "This request returns the list of OAuth applications for an instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe OAuth applications are ordered by descending creation date.\nMost recent OAuth applications will be returned first." }, { "info": { "name": "Create an OAuth Application", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/oauth_applications", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new OAuth application with the given name and callback URL for an instance.\nThe callback URL must be a valid URL.\nAll URL schemes are allowed such as `http://`, `https://`, `myapp://`, etc..." }, { "info": { "name": "Retrieve an OAuth Application by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/oauth_applications/:oauth_application_id", "params": [ { "name": "oauth_application_id", "value": "", "type": "path", "description": "The ID of the OAuth application" } ] }, "docs": "Fetches the OAuth application whose ID matches the provided `id` in the path." }, { "info": { "name": "Update an OAuth Application", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/oauth_applications/:oauth_application_id", "params": [ { "name": "oauth_application_id", "value": "", "type": "path", "description": "The ID of the OAuth application to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing OAuth application" }, { "info": { "name": "Delete an OAuth Application", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/oauth_applications/:oauth_application_id", "params": [ { "name": "oauth_application_id", "value": "", "type": "path", "description": "The ID of the OAuth application to delete" } ] }, "docs": "Deletes the given OAuth application.\nThis is not reversible." }, { "info": { "name": "Upload a Logo for the OAuth Application", "type": "http" }, "http": { "method": "PUT", "url": "https://api.clerk.com/v1/oauth_applications/:oauth_application_id/logo", "params": [ { "name": "oauth_application_id", "value": "", "type": "path", "description": "The ID of the OAuth application for which to upload a logo" } ], "body": { "type": "multipart-form", "data": [ { "name": "uploader_user_id", "type": "text", "value": "" }, { "name": "file", "type": "text", "value": "" } ] } }, "docs": "Set or replace an OAuth application's logo by uploading an image file.\nThis endpoint uses the `multipart/form-data` request content type and accepts a file of image type.\nThe file size cannot exceed 10MB.\nOnly the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`." }, { "info": { "name": "Rotate the Client Secret of the Given OAuth Application", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/oauth_applications/:oauth_application_id/rotate_secret", "params": [ { "name": "oauth_application_id", "value": "", "type": "path", "description": "The ID of the OAuth application for which to rotate the client secret" } ] }, "docs": "Rotates the OAuth application's client secret.\nWhen the client secret is rotated, make sure to update it in authorized OAuth clients." } ] }, { "info": { "name": "SAML Connections", "type": "folder" }, "items": [ { "info": { "name": "Get a List of SAML Connections for an Instance", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/saml_connections", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "query", "value": "", "type": "query", "description": "Returns SAML connections that have a name that matches the given query, via case-insensitive partial match." }, { "name": "order_by", "value": "", "type": "query", "description": "Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.\nBy prepending one of those values with + or -,\nwe can choose to sort in ascending (ASC) or descending (DESC) order." }, { "name": "organization_id", "value": "", "type": "query", "description": "Returns SAML connections that have an associated organization ID to the\ngiven organizations.\nFor each organization ID, the `+` and `-` can be\nprepended to the ID, which denote whether the\nrespective organization should be included or\nexcluded from the result set.\nAccepts up to 100 organization IDs." } ] }, "docs": "Returns the list of SAML Connections for an instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe SAML Connections are ordered by descending creation date and the most recent will be returned first.\nDeprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions." }, { "info": { "name": "Create a SAML Connection", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/saml_connections", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new SAML Connection.\nDeprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions." }, { "info": { "name": "Retrieve a SAML Connection by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/saml_connections/:saml_connection_id", "params": [ { "name": "saml_connection_id", "value": "", "type": "path", "description": "The ID of the SAML Connection" } ] }, "docs": "Fetches the SAML Connection whose ID matches the provided `saml_connection_id` in the path.\nDeprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions." }, { "info": { "name": "Update a SAML Connection", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/saml_connections/:saml_connection_id", "params": [ { "name": "saml_connection_id", "value": "", "type": "path", "description": "The ID of the SAML Connection to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the SAML Connection whose ID matches the provided `id` in the path.\nDeprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions." }, { "info": { "name": "Delete a SAML Connection", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/saml_connections/:saml_connection_id", "params": [ { "name": "saml_connection_id", "value": "", "type": "path", "description": "The ID of the SAML Connection to delete" } ] }, "docs": "Deletes the SAML Connection whose ID matches the provided `id` in the path.\nDeprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions." } ] }, { "info": { "name": "Enterprise Connections", "type": "folder" }, "items": [ { "info": { "name": "List Enterprise Connections", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/enterprise_connections", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "organization_id", "value": "", "type": "query", "description": "Filter enterprise connections by organization ID" }, { "name": "active", "value": "", "type": "query", "description": "Filter by active status. If true, only active connections are returned. If false, only inactive connections are returned. If omitted, all connections are returned." } ] }, "docs": "Returns the list of enterprise connections for the instance.\nResults can be paginated using the optional `limit` and `offset` query parameters." }, { "info": { "name": "Create an Enterprise Connection", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/enterprise_connections", "body": { "type": "json", "data": "{}" } }, "docs": "Create a new enterprise connection." }, { "info": { "name": "Retrieve an Enterprise Connection", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/enterprise_connections/:enterprise_connection_id", "params": [ { "name": "enterprise_connection_id", "value": "", "type": "path", "description": "The ID of the enterprise connection" } ] }, "docs": "Fetches the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path." }, { "info": { "name": "Update an Enterprise Connection", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/enterprise_connections/:enterprise_connection_id", "params": [ { "name": "enterprise_connection_id", "value": "", "type": "path", "description": "The ID of the enterprise connection to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path.\nWhen enabling the connection (setting `active` to true), any existing verified organization domains that match the connection's domains (e.g. used for enrollment modes like automatic invitation) may be deleted so the connection can be enabled." }, { "info": { "name": "Delete an Enterprise Connection", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/enterprise_connections/:enterprise_connection_id", "params": [ { "name": "enterprise_connection_id", "value": "", "type": "path", "description": "The ID of the enterprise connection to delete" } ] }, "docs": "Deletes the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path." } ] }, { "info": { "name": "Testing Tokens", "type": "folder" }, "items": [ { "info": { "name": "Retrieve a New Testing Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/testing_tokens" }, "docs": "Retrieve a new testing token." } ] }, { "info": { "name": "Agent Tasks", "type": "folder" }, "items": [ { "info": { "name": "Create Agent Task", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/agents/tasks", "body": { "type": "json", "data": "{}" } }, "docs": "Create an agent task on behalf of a user.\nThe response contains a URL that, when visited, creates a session for the user.\nThe agent_id is stable per agent_name within an instance. The agent_task_id is unique per call." }, { "info": { "name": "Revoke Agent Task", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/agents/tasks/:agent_task_id/revoke", "params": [ { "name": "agent_task_id", "value": "", "type": "path", "description": "The ID of the agent task to be revoked." } ] }, "docs": "Revokes a pending agent task." } ] }, { "info": { "name": "Waitlist Entries", "type": "folder" }, "items": [ { "info": { "name": "List All Waitlist Entries", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/waitlist_entries", "params": [ { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "query", "value": "", "type": "query", "description": "Filter waitlist entries by `email_address` or `id`" }, { "name": "status", "value": "", "type": "query", "description": "Filter waitlist entries by their status" }, { "name": "order_by", "value": "", "type": "query", "description": "Specify the order of results. Supported values are:\n- `created_at`\n- `email_address`\n- `invited_at`\n\nUse `+` for ascending or `-` for descending order. Defaults to `-created_at`." } ] }, "docs": "Retrieve a list of waitlist entries for the instance.\nEntries are ordered by creation date in descending order by default.\nSupports filtering by email address or status and pagination with limit and offset parameters." }, { "info": { "name": "Create a Waitlist Entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/waitlist_entries", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new waitlist entry for the given email address.\nIf the email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned." }, { "info": { "name": "Create Multiple Waitlist Entries", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/waitlist_entries/bulk", "body": { "type": "json", "data": "{}" } }, "docs": "Creates multiple waitlist entries for the provided email addresses.\nYou can choose whether to send confirmation emails by setting the `notify` parameter to `true` or `false` for each entry.\nIf the `notify` parameter is omitted, it defaults to `true`.\n\nIf an email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned.\nDuplicate email addresses within the same request are not allowed.\n\nThis endpoint is limited to a maximum of 50 entries p" }, { "info": { "name": "Delete a Pending Waitlist Entry", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/waitlist_entries/:waitlist_entry_id", "params": [ { "name": "waitlist_entry_id", "value": "", "type": "path", "description": "The ID of the waitlist entry to delete" } ] }, "docs": "Delete a pending waitlist entry." }, { "info": { "name": "Invite a Waitlist Entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/waitlist_entries/:waitlist_entry_id/invite", "params": [ { "name": "waitlist_entry_id", "value": "", "type": "path", "description": "The ID of the waitlist entry to invite" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Send an invite to the email address in a waitlist entry." }, { "info": { "name": "Reject a Waitlist Entry", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/waitlist_entries/:waitlist_entry_id/reject", "params": [ { "name": "waitlist_entry_id", "value": "", "type": "path", "description": "The ID of the waitlist entry to reject" } ] }, "docs": "Reject a waitlist entry." } ] }, { "info": { "name": "Billing", "type": "folder" }, "items": [ { "info": { "name": "List All Billing Plans", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/plans", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "payer_type", "value": "", "type": "query", "description": "Filter plans by payer type" } ] }, "docs": "Returns a list of all billing plans for the instance. The plans are returned sorted by creation date,\nwith the newest plans appearing first. This includes both free and paid plans. Pagination is supported." }, { "info": { "name": "List All Billing Prices", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/prices", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "plan_id", "value": "", "type": "query", "description": "Filter prices by plan ID" } ] }, "docs": "Returns a list of all prices for the instance. The prices are returned sorted by amount ascending,\nthen by creation date descending. This includes both default and custom prices. Pagination is supported." }, { "info": { "name": "Create a Custom Billing Price", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/billing/prices", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a custom price for a billing plan. Custom prices allow you to offer different pricing\nto specific customers while maintaining the same plan structure." }, { "info": { "name": "List All Subscription Items", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/subscription_items", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." }, { "name": "status", "value": "", "type": "query", "description": "Filter subscription items by status" }, { "name": "payer_type", "value": "", "type": "query", "description": "Filter subscription items by payer type" }, { "name": "plan_id", "value": "", "type": "query", "description": "Filter subscription items by plan ID" }, { "name": "include_free", "value": "", "type": "query", "description": "Whether to include free plan subscription items" }, { "name": "query", "value": "", "type": "query", "description": "Search query to filter subscription items" } ] }, "docs": "Returns a list of all subscription items for the instance. The subscription items are returned sorted by creation date,\nwith the newest appearing first. This includes subscriptions for both users and organizations. Pagination is supported." }, { "info": { "name": "Cancel a Subscription Item", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/billing/subscription_items/:subscription_item_id", "params": [ { "name": "subscription_item_id", "value": "", "type": "path", "description": "The ID of the subscription item to cancel" }, { "name": "end_now", "value": "", "type": "query", "description": "Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)" } ] }, "docs": "Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period." }, { "info": { "name": "Extend Free Trial for a Subscription Item", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/billing/subscription_items/:subscription_item_id/extend_free_trial", "params": [ { "name": "subscription_item_id", "value": "", "type": "path", "description": "The ID of the subscription item to extend the free trial for" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Extends the free trial period for a specific subscription item to the specified timestamp.\nThe subscription item must be currently in a free trial period, and the plan must support free trials.\nThe timestamp must be in the future and not more than 365 days from the end of the current trial period\nThis operation is idempotent - repeated requests with the same timestamp will not change the trial period." }, { "info": { "name": "Create a Price Transition for a Subscription Item", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/billing/subscription_items/:subscription_item_id/price_transition", "params": [ { "name": "subscription_item_id", "value": "", "type": "path", "description": "The ID of the subscription item to transition" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Creates a price transition for the specified subscription item.\nThis may create an upcoming subscription item or activate immediately depending on plan and payer rules." }, { "info": { "name": "List All Billing Statements", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/statements", "params": [ { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of all billing statements for the instance. The statements are returned sorted by creation date,\nwith the newest statements appearing first. Pagination is supported." }, { "info": { "name": "Retrieve a Billing Statement", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/statements/:statementID", "params": [ { "name": "statementID", "value": "", "type": "path", "description": "The ID of the statement to retrieve." } ] }, "docs": "Retrieves the details of a billing statement." }, { "info": { "name": "List Payment Attempts for a Billing Statement", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/billing/statements/:statementID/payment_attempts", "params": [ { "name": "statementID", "value": "", "type": "path", "description": "The ID of the statement to retrieve payment attempts for." }, { "name": "paginated", "value": "", "type": "query", "description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of all payment attempts for a specific billing statement. The payment attempts are returned sorted by creation date,\nwith the newest payment attempts appearing first. Pagination is supported." } ] }, { "info": { "name": "Organization Permissions", "type": "folder" }, "items": [ { "info": { "name": "Get a List of All Organization Permissions", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_permissions", "params": [ { "name": "query", "value": "", "type": "query", "description": "Returns organization permissions with ID, name, or key that match the given query.\nUses exact match for permission ID and partial match for name and key." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return organization permissions in a particular order.\nAt the moment, you can order the returned permissions by their `created_at`, `name`, or `key`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want permissions to be returned in descending order according to their `created_at` property, you can use `-created_at`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Retrieves all organization permissions for the given instance." }, { "info": { "name": "Create a New Organization Permission", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/organization_permissions", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new organization permission for the given instance." }, { "info": { "name": "Get an Organization Permission", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/organization_permissions/:permission_id", "params": [ { "name": "permission_id", "value": "", "type": "path", "description": "The ID of the permission to retrieve" } ] }, "docs": "Retrieves the details of an organization permission." }, { "info": { "name": "Update an Organization Permission", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/organization_permissions/:permission_id", "params": [ { "name": "permission_id", "value": "", "type": "path", "description": "The ID of the permission to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates the properties of an existing organization permission.\nSystem permissions cannot be updated." }, { "info": { "name": "Delete an Organization Permission", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/organization_permissions/:permission_id", "params": [ { "name": "permission_id", "value": "", "type": "path", "description": "The ID of the permission to delete" } ] }, "docs": "Deletes an organization permission.\nSystem permissions cannot be deleted." } ] }, { "info": { "name": "Role Sets", "type": "folder" }, "items": [ { "info": { "name": "Get a List of Role Sets", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/role_sets", "params": [ { "name": "query", "value": "", "type": "query", "description": "Returns role sets with ID, name, or key that match the given query.\nUses exact match for role set ID and partial match for name and key." }, { "name": "order_by", "value": "", "type": "query", "description": "Allows to return role sets in a particular order.\nAt the moment, you can order the returned role sets by their `created_at`, `name`, or `key`.\nIn order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.\nFor example, if you want role sets to be returned in descending order according to their `created_at` property, you can use `-created_at`.\nIf you don't use `+` or `-`, then `+` is implied.\nDefaults to `-created_at`." }, { "name": "limit", "value": "", "type": "query", "description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`." }, { "name": "offset", "value": "", "type": "query", "description": "Skip the first `offset` results when paginating.\nNeeds to be an integer greater or equal to zero.\nTo be used in conjunction with `limit`." } ] }, "docs": "Returns a list of role sets for the instance.\nResults can be paginated using the optional `limit` and `offset` query parameters.\nThe role sets are ordered by descending creation date by default." }, { "info": { "name": "Create a Role Set", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/role_sets", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new role set with the given name and roles.\nThe key must be unique for the instance and start with the 'role_set:' prefix, followed by lowercase alphanumeric characters and underscores only.\nYou must provide at least one role and specify a default role key and creator role key." }, { "info": { "name": "Retrieve a Role Set", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/role_sets/:role_set_key_or_id", "params": [ { "name": "role_set_key_or_id", "value": "", "type": "path", "description": "The key or ID of the role set" } ] }, "docs": "Retrieves an existing role set by its key or ID." }, { "info": { "name": "Update a Role Set", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/role_sets/:role_set_key_or_id", "params": [ { "name": "role_set_key_or_id", "value": "", "type": "path", "description": "The key or ID of the role set to update" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Updates an existing role set.\nYou can update the name, key, description, type, default role, or creator role.\nAll parameters are optional - you can update only the fields you want to change." }, { "info": { "name": "Replace a Role Set", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/role_sets/:role_set_key_or_id/replace", "params": [ { "name": "role_set_key_or_id", "value": "", "type": "path", "description": "The key or ID of the role set to replace" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Replaces a role set with another role set. This is functionally equivalent to deleting\nthe role set but allows for atomic replacement with migration support.\nOrganizations using this role set will be migrated to the destination role set." }, { "info": { "name": "Add Roles to a Role Set", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/role_sets/:role_set_key_or_id/roles", "params": [ { "name": "role_set_key_or_id", "value": "", "type": "path", "description": "The key or ID of the role set" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Adds one or more roles to an existing role set.\nYou can optionally update the default role or creator role when adding new roles." }, { "info": { "name": "Replace a Role in a Role Set", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/role_sets/:role_set_key_or_id/roles/replace", "params": [ { "name": "role_set_key_or_id", "value": "", "type": "path", "description": "The key or ID of the role set" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Replaces a role in a role set with another role. This atomically removes\nthe source role and reassigns any members to the destination role." } ] }, { "info": { "name": "API Keys", "type": "folder" }, "items": [ { "info": { "name": "Get API Keys", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/api_keys", "params": [ { "name": "type", "value": "", "type": "query" }, { "name": "subject", "value": "", "type": "query" }, { "name": "include_invalid", "value": "", "type": "query" }, { "name": "limit", "value": "", "type": "query" }, { "name": "offset", "value": "", "type": "query" }, { "name": "query", "value": "", "type": "query" } ] }, "docs": "Get API Keys" }, { "info": { "name": "Create an API Key", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/api_keys", "body": { "type": "json", "data": "{}" } }, "docs": "Create an API Key" }, { "info": { "name": "Get an API Key by ID", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/api_keys/:apiKeyID", "params": [ { "name": "apiKeyID", "value": "", "type": "path" } ] }, "docs": "Get an API Key by ID" }, { "info": { "name": "Update an API Key", "type": "http" }, "http": { "method": "PATCH", "url": "https://api.clerk.com/v1/api_keys/:apiKeyID", "params": [ { "name": "apiKeyID", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Update an API Key" }, { "info": { "name": "Delete an API Key", "type": "http" }, "http": { "method": "DELETE", "url": "https://api.clerk.com/v1/api_keys/:apiKeyID", "params": [ { "name": "apiKeyID", "value": "", "type": "path" } ] }, "docs": "Delete an API Key" }, { "info": { "name": "Get an API Key Secret", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/api_keys/:apiKeyID/secret", "params": [ { "name": "apiKeyID", "value": "", "type": "path" } ] }, "docs": "Get an API Key Secret" }, { "info": { "name": "Revoke an API Key", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/api_keys/:apiKeyID/revoke", "params": [ { "name": "apiKeyID", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Revoke an API Key" }, { "info": { "name": "Verify an API Key", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/api_keys/verify", "body": { "type": "json", "data": "{}" } }, "docs": "Verify an API Key" } ] }, { "info": { "name": "M2M Tokens", "type": "folder" }, "items": [ { "info": { "name": "Get M2M Tokens", "type": "http" }, "http": { "method": "GET", "url": "https://api.clerk.com/v1/m2m_tokens", "params": [ { "name": "subject", "value": "", "type": "query" }, { "name": "revoked", "value": "", "type": "query" }, { "name": "expired", "value": "", "type": "query" }, { "name": "limit", "value": "", "type": "query" }, { "name": "offset", "value": "", "type": "query" } ] }, "docs": "Fetches M2M tokens for a specific machine.\n\nOnly tokens created with the opaque token format are returned by this endpoint. JWT-format M2M tokens are stateless and are not stored.\n\nThis endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.\n\n- When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved.\n- When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be re" }, { "info": { "name": "Create a M2M Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/m2m_tokens", "body": { "type": "json", "data": "{}" } }, "docs": "Creates a new M2M Token. Must be authenticated via a Machine Secret Key." }, { "info": { "name": "Revoke a M2M Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/m2m_tokens/:m2m_token_id/revoke", "params": [ { "name": "m2m_token_id", "value": "", "type": "path" } ], "body": { "type": "json", "data": "{}" } }, "docs": "Revokes a M2M Token.\n\nThis endpoint only revokes stored opaque-format M2M tokens. JWT-format M2M tokens are stateless and cannot be revoked.\n\nThis endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.\n\n- When revoking a M2M Token with a Machine Secret Key, the token must managed by the Machine associated with the Machine Secret Key.\n- When revoking a M2M Token with a Clerk Secret Key, any token on the Instance can be revoked." }, { "info": { "name": "Verify a M2M Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/m2m_tokens/verify", "body": { "type": "json", "data": "{}" } }, "docs": "Verifies a M2M Token.\n\nThis endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.\n\n- When verifying a M2M Token with a Machine Secret Key, the token must be granted access to the Machine associated with the Machine Secret Key.\n- When verifying a M2M Token with a Clerk Secret Key, any token on the Instance can be verified." } ] }, { "info": { "name": "OAuth Access Tokens", "type": "folder" }, "items": [ { "info": { "name": "Verify an OAuth Access Token", "type": "http" }, "http": { "method": "POST", "url": "https://api.clerk.com/v1/oauth_applications/access_tokens/verify", "body": { "type": "json", "data": "{}" } }, "docs": "Verify an OAuth Access Token" } ] } ], "bundled": true }