Skip to content

Instantly share code, notes, and snippets.

@RhysSullivan

RhysSullivan/clerk-bapi.json

Created February 18, 2026 02:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save RhysSullivan/24bcf81063cd2ff96c01801f20d6087a to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save RhysSullivan/24bcf81063cd2ff96c01801f20d6087a to your computer and use it in GitHub Desktop.
Download ZIP
Clerk Backend API OpenAPI spec (converted from YAML)
Raw
clerk-bapi.json
{
"openapi": "3.0.3",
"info": {
"title": "Clerk Backend API",
"x-logo": {
"url": "https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75",
"altText": "Clerk docs",
"href": "https://clerk.com/docs"
},
"contact": {
"email": "support@clerk.com",
"name": "Clerk Platform Team",
"url": "https://clerk.com/support"
},
"description": "The Clerk REST Backend API, meant to be accessed by backend servers.\n\n### Versions\n\nWhen the API changes in a way that isn't compatible with older versions, a new version is released.\nEach version is identified by its release date, e.g. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions).\n\nPlease see https://clerk.com/docs for more information.",
"version": "2025-11-10",
"termsOfService": "https://clerk.com/terms",
"license": {
"name": "MIT",
"url": "https://github.com/clerk/openapi-specs/blob/main/LICENSE"
}
},
"servers": [
{
"url": "https://api.clerk.com/v1"
}
],
"security": [
{
"bearerAuth": [
]
}
],
"tags": [
{
"name": "Actor Tokens",
"description": "Allow your users to sign in on behalf of other users.",
"externalDocs": {
"url": "https://clerk.com/docs/authentication/user-impersonation#actor-tokens"
}
},
{
"name": "Allow-list / Block-list",
"description": "Allow-lists and Block-lists allow you to control who can sign up or sign in\nto your application, by restricting access based on the user's email\naddress or phone number.",
"externalDocs": {
"url": "https://clerk.com/docs/authentication/allowlist"
}
},
{
"name": "Clients",
"description": "The Client object tracks sessions, as well as the state of any sign in and sign up attempts, for a given device.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/client"
}
},
{
"name": "Billing",
"description": "Billing-related endpoints for managing statements and payment attempts.",
"externalDocs": {
"url": "https://clerk.com/docs/billing/overview"
}
},
{
"name": "Domains",
"description": "Domains represent each instance's URLs and DNS setup."
},
{
"name": "Email Addresses",
"description": "A user can be associated with one or more email addresses, which allows them to be contacted via email.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/types/email-address"
}
},
{
"name": "Email & SMS Templates",
"description": "Email & SMS templates allow you to customize the theming and wording of emails & SMS messages that are sent by your instance.",
"externalDocs": {
"url": "https://clerk.com/docs/authentication/email-sms-templates"
}
},
{
"name": "Instance Settings",
"description": "Modify the settings of your instance."
},
{
"name": "Invitations",
"description": "Invitations allow you to invite someone to sign up to your application, via email.",
"externalDocs": {
"url": "https://clerk.com/docs/authentication/invitations"
}
},
{
"name": "JWKS",
"description": "Retrieve the JSON Web Key Set which can be used to verify the token signatures of the instance."
},
{
"name": "JWT Templates",
"description": "JWT Templates allow you to generate custom authentication tokens\ntied to authenticated sessions, enabling you to integrate with third-party\nservices.",
"externalDocs": {
"url": "https://clerk.com/docs/request-authentication/jwt-templates"
}
},
{
"name": "OAuth Applications",
"description": "OAuth applications contain data for clients using Clerk as an OAuth2 identity provider."
},
{
"name": "OAuth Access Tokens",
"description": "Endpoints for managing OAuth Access Tokens, which are credentials to access protected resources on behalf of a user."
},
{
"name": "Organizations",
"description": "Organizations are used to group members under a common entity and provide shared access to resources.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/overview"
}
},
{
"name": "Organization Invitations",
"description": "Invite users to an organization.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/invite-users"
}
},
{
"name": "Organization Memberships",
"description": "Manage member roles in an organization.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/manage-member-roles"
}
},
{
"name": "Organization Permissions",
"description": "Manage organization permissions that define what members can do within an organization.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/manage-member-roles"
}
},
{
"name": "Organization Roles",
"description": "Manage custom roles in an organization.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/manage-member-roles"
}
},
{
"name": "Role Sets",
"description": "Role sets define collections of roles that can be assigned to organization members.\nEach organization uses one role set to determine the available roles for its members.\nRole sets support default roles for new members and creator roles for organization founders.",
"externalDocs": {
"url": "https://clerk.com/docs/organizations/manage-member-roles"
}
},
{
"name": "Phone Numbers",
"description": "A user can be associated with one or more phone numbers, which allows them to be contacted via SMS.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/types/phone-number"
}
},
{
"name": "Redirect URLs",
"description": "Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo).\nIn these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs."
},
{
"name": "SAML Connections",
"description": "A SAML Connection holds configuration data required for facilitating a SAML SSO flow between your\nClerk Instance (SP) and a particular SAML IdP."
},
{
"name": "Sessions",
"description": "The Session object is an abstraction over an HTTP session.\nIt models the period of information exchange between a user and the server.\nSessions are created when a user successfully goes through the sign in or sign up flows.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/session"
}
},
{
"name": "Machines",
"description": "A Machine represents a machine/server/service which can be used in machine-to-machine authentication."
},
{
"name": "M2M Tokens",
"description": "Machine to Machine Tokens are used to manage authentication between Machines."
},
{
"name": "API Keys",
"description": "Endpoints for managing API Keys"
},
{
"name": "Sign-in Tokens",
"description": "Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials.\nA sign-in token can be used at most once and they can be consumed from the Frontend API using the `ticket` strategy."
},
{
"name": "Sign Ups",
"description": "Sign-up objects track the progress of a sign-up attempt and store any field collected from user input.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/sign-up"
}
},
{
"name": "Testing Tokens",
"description": "Tokens meant for use by end-to-end test suites in requests to the Frontend API, so as to bypass bot detection measures.",
"externalDocs": {
"url": "https://clerk.com/docs/testing/overview#testing-tokens"
}
},
{
"name": "Users",
"description": "The user object represents a user that has successfully signed up to your application.",
"externalDocs": {
"url": "https://clerk.com/docs/references/javascript/user"
}
},
{
"name": "Webhooks",
"description": "You can configure webhooks to be notified about various events that happen on your instance.",
"externalDocs": {
"url": "https://clerk.com/docs/integration/webhooks"
}
},
{
"name": "Miscellaneous",
"description": "Various endpoints that do not belong in any particular category."
},
{
"name": "Beta Features",
"description": "Modify instance settings that are currently in beta."
},
{
"name": "Waitlist Entries",
"description": "Manage waitlist entries."
},
{
"name": "Proxy Checks",
"description": "Check if a user is using a proxy."
},
{
"name": "Organization Domains",
"description": "Manage organization domains."
},
{
"name": "Accountless Applications",
"description": "Create and complete accountless applications. Note that this is an experimental feature and subject to change or be removed without notice."
}
],
"externalDocs": {
"url": "https://clerk.com/docs"
},
"paths": {
"/public/interstitial": {
"get": {
"operationId": "GetPublicInterstitial",
"x-speakeasy-group": "miscellaneous",
"x-speakeasy-name-override": "getPublicInterstitial",
"security": [
],
"summary": "Returns the markup for the interstitial page",
"description": "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.",
"tags": [
"Miscellaneous"
],
"parameters": [
{
"name": "frontendApi",
"deprecated": true,
"in": "query",
"required": false,
"description": "Please use `frontend_api` instead",
"schema": {
"type": "string"
}
},
{
"name": "frontend_api",
"in": "query",
"required": false,
"description": "The Frontend API key of your instance",
"schema": {
"type": "string"
}
},
{
"name": "publishable_key",
"in": "query",
"required": false,
"description": "The publishable key of your instance",
"schema": {
"type": "string"
}
},
{
"name": "proxy_url",
"in": "query",
"required": false,
"description": "The proxy URL of your instance",
"schema": {
"type": "string"
}
},
{
"name": "domain",
"in": "query",
"required": false,
"description": "The domain of your instance",
"schema": {
"type": "string"
}
},
{
"name": "sign_in_url",
"in": "query",
"required": false,
"description": "The sign in URL of your instance",
"schema": {
"type": "string"
}
},
{
"name": "use_domain_for_script",
"in": "query",
"required": false,
"description": "Whether to use the domain for the script URL",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"description": "The interstitial page markup"
},
"400": {
"description": "A required query parameter is missing"
},
"500": {
"description": "An infinite redirect loop was detected"
}
}
}
},
"/jwks": {
"get": {
"operationId": "GetJWKS",
"x-speakeasy-group": "jwks",
"x-speakeasy-name-override": "getJWKS",
"summary": "Retrieve the JSON Web Key Set of the instance",
"description": "Retrieve the JSON Web Key Set of the instance",
"tags": [
"JWKS"
],
"responses": {
"200": {
"$ref": "#/components/responses/WellKnown.JWKS"
}
}
}
},
"/aws_credentials": {
},
"/aws_credentials/{id}": {
},
"/clients": {
"get": {
"deprecated": true,
"operationId": "GetClientList",
"x-speakeasy-group": "clients",
"x-speakeasy-name-override": "list",
"tags": [
"Clients"
],
"summary": "List all clients",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Client.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"410": {
"$ref": "#/components/responses/DeprecatedEndpoint"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/clients/verify": {
"post": {
"operationId": "VerifyClient",
"x-speakeasy-group": "clients",
"x-speakeasy-name-override": "verify",
"tags": [
"Clients"
],
"summary": "Verify a client",
"description": "Verifies the client in the provided token",
"requestBody": {
"description": "Parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"token": {
"type": "string",
"description": "A JWT that represents the active client."
}
},
"required": [
"token"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Client"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/clients/{client_id}": {
"get": {
"operationId": "GetClient",
"x-speakeasy-group": "clients",
"x-speakeasy-name-override": "get",
"tags": [
"Clients"
],
"summary": "Get a client",
"description": "Returns the details of a client.",
"parameters": [
{
"name": "client_id",
"in": "path",
"description": "Client ID.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Client"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/clients/handshake_payload": {
},
"/email_addresses": {
"post": {
"operationId": "CreateEmailAddress",
"x-speakeasy-group": "emailAddresses",
"x-speakeasy-name-override": "create",
"tags": [
"Email Addresses"
],
"summary": "Create an email address",
"description": "Create a new email address",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The ID representing the user"
},
"email_address": {
"type": "string",
"description": "The new email address. Must adhere to the RFC 5322 specification for email address format."
},
"verified": {
"type": "boolean",
"description": "When created, the email address will be marked as verified.",
"nullable": true
},
"primary": {
"type": "boolean",
"description": "Create this email address as the primary email address for the user.\nDefault: false, unless it is the first email address.",
"nullable": true
}
},
"required": [
"user_id",
"email_address"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/EmailAddress"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/email_addresses/{email_address_id}": {
"get": {
"operationId": "GetEmailAddress",
"x-speakeasy-group": "emailAddresses",
"x-speakeasy-name-override": "get",
"x-speakeasy-usage-example": true,
"tags": [
"Email Addresses"
],
"summary": "Retrieve an email address",
"description": "Returns the details of an email address.",
"parameters": [
{
"name": "email_address_id",
"in": "path",
"description": "The ID of the email address to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/EmailAddress"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"delete": {
"operationId": "DeleteEmailAddress",
"x-speakeasy-group": "emailAddresses",
"x-speakeasy-name-override": "delete",
"tags": [
"Email Addresses"
],
"summary": "Delete an email address",
"description": "Delete the email address with the given ID",
"parameters": [
{
"name": "email_address_id",
"in": "path",
"description": "The ID of the email address to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateEmailAddress",
"x-speakeasy-group": "emailAddresses",
"x-speakeasy-name-override": "update",
"tags": [
"Email Addresses"
],
"summary": "Update an email address",
"description": "Updates an email address.",
"parameters": [
{
"name": "email_address_id",
"in": "path",
"description": "The ID of the email address to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verified": {
"type": "boolean",
"description": "The email address will be marked as verified.",
"nullable": true
},
"primary": {
"type": "boolean",
"description": "Set this email address as the primary email address for the user.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/EmailAddress"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/phone_numbers": {
"post": {
"operationId": "CreatePhoneNumber",
"x-speakeasy-group": "phoneNumbers",
"x-speakeasy-name-override": "create",
"tags": [
"Phone Numbers"
],
"summary": "Create a phone number",
"description": "Create a new phone number",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The ID representing the user"
},
"phone_number": {
"type": "string",
"description": "The new phone number. Must adhere to the E.164 standard for phone number format."
},
"verified": {
"type": "boolean",
"description": "When created, the phone number will be marked as verified.",
"nullable": true
},
"primary": {
"type": "boolean",
"description": "Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number.",
"nullable": true
},
"reserved_for_second_factor": {
"type": "boolean",
"description": "Create this phone number as reserved for multi-factor authentication. The phone number must also be verified.\nIf there are no other reserved second factors, the phone number will be set as the default second factor.",
"nullable": true
}
},
"required": [
"user_id",
"phone_number"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/PhoneNumber"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/phone_numbers/{phone_number_id}": {
"get": {
"operationId": "GetPhoneNumber",
"x-speakeasy-group": "phoneNumbers",
"x-speakeasy-name-override": "get",
"tags": [
"Phone Numbers"
],
"summary": "Retrieve a phone number",
"description": "Returns the details of a phone number",
"parameters": [
{
"name": "phone_number_id",
"in": "path",
"description": "The ID of the phone number to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/PhoneNumber"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"delete": {
"operationId": "DeletePhoneNumber",
"x-speakeasy-group": "phoneNumbers",
"x-speakeasy-name-override": "delete",
"tags": [
"Phone Numbers"
],
"summary": "Delete a phone number",
"description": "Delete the phone number with the given ID",
"parameters": [
{
"name": "phone_number_id",
"in": "path",
"description": "The ID of the phone number to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdatePhoneNumber",
"x-speakeasy-group": "phoneNumbers",
"x-speakeasy-name-override": "update",
"tags": [
"Phone Numbers"
],
"summary": "Update a phone number",
"description": "Updates a phone number",
"parameters": [
{
"name": "phone_number_id",
"in": "path",
"description": "The ID of the phone number to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"verified": {
"type": "boolean",
"description": "The phone number will be marked as verified.",
"nullable": true
},
"primary": {
"type": "boolean",
"description": "Set this phone number as the primary phone number for the user.",
"nullable": true
},
"reserved_for_second_factor": {
"type": "boolean",
"description": "Set this phone number as reserved for multi-factor authentication.\nThe phone number must also be verified.\nIf there are no other reserved second factors, the phone number will be set as the default second factor.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/PhoneNumber"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sessions": {
"get": {
"operationId": "GetSessionList",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "list",
"tags": [
"Sessions"
],
"summary": "List all sessions",
"description": "Returns a list of all sessions.\nThe sessions are returned sorted by creation date, with the newest sessions appearing first.\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 provided.",
"parameters": [
{
"name": "client_id",
"in": "query",
"required": false,
"description": "List sessions for the given client",
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "query",
"required": false,
"description": "List sessions for the given user",
"schema": {
"type": "string"
}
},
{
"name": "status",
"in": "query",
"required": false,
"description": "Filter sessions by the provided status",
"schema": {
"type": "string",
"enum": [
"abandoned",
"active",
"ended",
"expired",
"removed",
"replaced",
"revoked"
]
}
},
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Session.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "createSession",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "create",
"tags": [
"Sessions"
],
"summary": "Create a new active session",
"description": "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.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The ID representing the user"
},
"active_organization_id": {
"type": "string",
"description": "The ID of the organization to set as active for this session"
}
},
"required": [
"user_id"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Session"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/sessions/{session_id}": {
"get": {
"operationId": "GetSession",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "get",
"tags": [
"Sessions"
],
"summary": "Retrieve a session",
"description": "Retrieve the details of a session",
"parameters": [
{
"name": "session_id",
"in": "path",
"description": "The ID of the session",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Session"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sessions/{session_id}/refresh": {
"post": {
"operationId": "RefreshSession",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "refresh",
"tags": [
"Sessions"
],
"summary": "Refresh a session",
"description": "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.",
"parameters": [
{
"name": "session_id",
"in": "path",
"description": "The ID of the session",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Refresh session parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"expired_token": {
"type": "string",
"description": "The JWT that is sent via the `__session` cookie from your frontend.\nNote: this JWT must be associated with the supplied session ID."
},
"refresh_token": {
"type": "string",
"description": "The refresh token from the `__refresh` cookie set via FAPI's handshake flow."
},
"request_origin": {
"type": "string",
"description": "The origin of the request."
},
"request_headers": {
"type": "object",
"additionalProperties": true,
"description": "The headers of the request.",
"nullable": true
},
"format": {
"type": "string",
"description": "The format of the response.",
"nullable": true,
"default": "token",
"enum": [
"token",
"cookie"
]
},
"request_originating_ip": {
"type": "string",
"description": "The IP address of the request.",
"nullable": true
}
},
"required": [
"expired_token",
"refresh_token",
"request_origin"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Session.Refresh"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
}
}
}
},
"/sessions/{session_id}/revoke": {
"post": {
"operationId": "RevokeSession",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "revoke",
"tags": [
"Sessions"
],
"summary": "Revoke a session",
"description": "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.",
"parameters": [
{
"name": "session_id",
"in": "path",
"description": "The ID of the session",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Session"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sessions/{session_id}/tokens": {
"post": {
"operationId": "CreateSessionToken",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "createToken",
"tags": [
"Sessions"
],
"summary": "Create a session token",
"description": "Creates a session JSON Web Token (JWT) based on a session.",
"parameters": [
{
"name": "session_id",
"in": "path",
"description": "The ID of the session",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expires_in_seconds": {
"type": "integer",
"minimum": 30,
"maximum": 315360000,
"description": "Use this parameter to override the default session token lifetime.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"token"
]
},
"jwt": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sessions/{session_id}/tokens/{template_name}": {
"post": {
"operationId": "CreateSessionTokenFromTemplate",
"x-speakeasy-group": "sessions",
"x-speakeasy-name-override": "createTokenFromTemplate",
"tags": [
"Sessions"
],
"summary": "Create a session token from a JWT template",
"description": "Creates a JSON Web Token (JWT) based on a session and a JWT Template name defined for your instance",
"parameters": [
{
"name": "session_id",
"in": "path",
"description": "The ID of the session",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "template_name",
"in": "path",
"description": "The name of the JWT template defined in your instance (e.g. `custom_hasura`).",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"expires_in_seconds": {
"type": "integer",
"minimum": 30,
"maximum": 315360000,
"description": "Use this parameter to override the JWT lifetime.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"token"
]
},
"jwt": {
"type": "string"
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/templates/{template_type}": {
"get": {
"deprecated": true,
"operationId": "GetTemplateList",
"x-speakeasy-group": "emailSMSTemplates",
"x-speakeasy-name-override": "list",
"summary": "List all templates",
"description": "Returns a list of all templates.\nThe templates are returned sorted by position.",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of templates to list (email or SMS)",
"required": true,
"schema": {
"type": "string",
"enum": [
"email",
"sms"
]
}
},
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Template.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/templates/{template_type}/{slug}": {
"get": {
"deprecated": true,
"operationId": "GetTemplate",
"x-speakeasy-group": "emailSMSTemplates",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a template",
"description": "Returns the details of a template",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of templates to retrieve (email or SMS)",
"required": true,
"schema": {
"type": "string",
"enum": [
"email",
"sms"
]
}
},
{
"name": "slug",
"in": "path",
"description": "The slug (i.e. machine-friendly name) of the template to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Template"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"put": {
"deprecated": true,
"operationId": "UpsertTemplate",
"x-speakeasy-group": "emailAndSmsTemplates",
"x-speakeasy-name-override": "upsert",
"summary": "Update a template for a given type and slug",
"description": "Updates the existing template of the given type and slug",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of template to update",
"required": true,
"schema": {
"type": "string",
"enum": [
"email",
"sms"
]
}
},
{
"name": "slug",
"in": "path",
"description": "The slug of the template to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The user-friendly name of the template"
},
"subject": {
"type": "string",
"description": "The email subject.\nApplicable only to email templates.",
"nullable": true
},
"markup": {
"type": "string",
"description": "The editor markup used to generate the body of the template",
"nullable": true
},
"body": {
"type": "string",
"description": "The template body before variable interpolation"
},
"delivered_by_clerk": {
"type": "boolean",
"description": "Whether Clerk should deliver emails or SMS messages based on the current template",
"nullable": true
},
"from_email_name": {
"type": "string",
"description": "The local part of the From email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
},
"reply_to_email_name": {
"type": "string",
"description": "The local part of the Reply To email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Template"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/templates/{template_type}/{slug}/revert": {
"post": {
"deprecated": true,
"operationId": "RevertTemplate",
"x-speakeasy-group": "emailSMSTemplates",
"x-speakeasy-name-override": "revert",
"summary": "Revert a template",
"description": "Reverts an updated template to its default state",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of template to revert",
"required": true,
"schema": {
"type": "string",
"enum": [
"email",
"sms"
]
}
},
{
"name": "slug",
"in": "path",
"description": "The slug of the template to revert",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Template"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/templates/{template_type}/{slug}/preview": {
"post": {
"deprecated": true,
"operationId": "PreviewTemplate",
"x-speakeasy-group": "templates",
"x-speakeasy-name-override": "preview",
"summary": "Preview changes to a template",
"description": "Returns a preview of a template for a given template_type, slug and body",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of template to preview",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "slug",
"in": "path",
"description": "The slug of the template to preview",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"subject": {
"type": "string",
"description": "The email subject.\nApplicable only to email templates.",
"nullable": true
},
"body": {
"type": "string",
"description": "The template body before variable interpolation"
},
"from_email_name": {
"type": "string",
"description": "The local part of the From email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
},
"reply_to_email_name": {
"type": "string",
"description": "The local part of the Reply To email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/templates/{template_type}/{slug}/toggle_delivery": {
"post": {
"deprecated": true,
"operationId": "ToggleTemplateDelivery",
"x-speakeasy-group": "emailSMSTemplates",
"x-speakeasy-name-override": "toggleTemplateDelivery",
"summary": "Toggle the delivery by Clerk for a template of a given type and slug",
"description": "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.",
"tags": [
"Email & SMS Templates"
],
"parameters": [
{
"name": "template_type",
"in": "path",
"description": "The type of template to toggle delivery for",
"required": true,
"schema": {
"type": "string",
"enum": [
"email",
"sms"
]
}
},
{
"name": "slug",
"in": "path",
"description": "The slug of the template for which to toggle delivery",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"delivered_by_clerk": {
"type": "boolean",
"description": "Whether Clerk should deliver emails or SMS messages based on the current template"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Template"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/users": {
"get": {
"operationId": "GetUserList",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "list",
"summary": "List all users",
"description": "Returns a list of all users.\nThe users are returned sorted by creation date, with the newest users appearing first.",
"tags": [
"Users"
],
"parameters": [
{
"name": "email_address",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified email addresses.\nAccepts up to 100 email addresses.\nAny email addresses not found are ignored.",
"required": false
},
{
"name": "phone_number",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified phone numbers.\nAccepts up to 100 phone numbers.\nAny phone numbers not found are ignored.",
"required": false
},
{
"name": "external_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"name": "username",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored.",
"required": false
},
{
"name": "web3_wallet",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored.",
"required": false
},
{
"name": "user_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"name": "organization_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"name": "query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "email_address_query",
"in": "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`.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "phone_number_query",
"in": "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`.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "username_query",
"in": "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`.",
"schema": {
"type": "string"
}
},
{
"name": "name_query",
"in": "query",
"description": "Returns users with names that match the given query, via case-insensitive partial match.",
"schema": {
"type": "string"
}
},
{
"name": "banned",
"in": "query",
"required": false,
"description": "Returns users which are either banned (`banned=true`) or not banned (`banned=false`).",
"schema": {
"type": "boolean"
}
},
{
"name": "last_active_at_before",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_active_at_after",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_active_at_since",
"in": "query",
"deprecated": true,
"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`.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_before",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_after",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"name": "last_sign_in_at_before",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_sign_in_at_after",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "provider",
"in": "query",
"schema": {
"type": "string"
},
"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.",
"required": false
},
{
"name": "provider_user_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"name": "order_by",
"in": "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.",
"schema": {
"type": "string",
"default": "-created_at"
},
"required": false
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "create",
"summary": "Create a new user",
"description": "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 instances",
"tags": [
"Users"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"external_id": {
"type": "string",
"description": "The ID of the user as used in your external systems or your previous authentication solution.\nMust be unique across your instance.",
"nullable": true
},
"first_name": {
"type": "string",
"description": "The first name to assign to the user",
"nullable": true
},
"last_name": {
"type": "string",
"description": "The last name to assign to the user",
"nullable": true
},
"locale": {
"type": "string",
"description": "The locale to assign to the user (e.g., \"en-US\", \"fr-FR\")",
"nullable": true
},
"email_address": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses to add to the user.\nMust be unique across your instance.\nThe first email address will be set as the user's primary email address."
},
"phone_number": {
"type": "array",
"items": {
"type": "string"
},
"description": "Phone numbers to add to the user.\nMust be unique across your instance.\nThe first phone number will be set as the user's primary phone number."
},
"web3_wallet": {
"type": "array",
"items": {
"type": "string"
},
"description": "Web3 wallets to add to the user.\nMust be unique across your instance.\nThe first wallet will be set as the user's primary wallet."
},
"username": {
"type": "string",
"description": "The username to give to the user.\nIt must be unique across your instance.",
"nullable": true
},
"password": {
"type": "string",
"description": "The plaintext password to give the user.\nMust be at least 8 characters long, and cannot be in any list of hacked passwords.",
"nullable": true
},
"password_digest": {
"type": "string",
"description": "In case you already have the password digests and not the passwords, you can use them for the newly created user via this property.\nThe digests should be generated with one of the supported algorithms.\nThe hashing algorithm can be specified using the `password_hasher` property.",
"nullable": true
},
"password_hasher": {
"$ref": "#/components/schemas/PasswordHasher"
},
"skip_password_checks": {
"type": "boolean",
"description": "When set to `true` all password checks are skipped.\nIt is recommended to use this method only when migrating plaintext passwords to Clerk.\nUpon migration the user base should be prompted to pick stronger password.",
"nullable": true
},
"skip_password_requirement": {
"type": "boolean",
"description": "When set to `true`, `password` is not required anymore when creating the user and can be omitted.\nThis is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords.\nPlease note that you cannot use this flag if password is the only way for a user to sign into your instance.",
"nullable": true
},
"totp_secret": {
"type": "string",
"description": "In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it.\nPlease note that currently the supported options are:\n* Period: 30 seconds\n* Code length: 6 digits\n* Algorithm: SHA1",
"nullable": true
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them.\nYou must provide the backup codes in plain format or the corresponding bcrypt digest."
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is visible to both your Frontend and Backend APIs",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is only visible to your Backend API",
"additionalProperties": true
},
"unsafe_metadata": {
"type": "object",
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe.",
"additionalProperties": true
},
"delete_self_enabled": {
"type": "boolean",
"description": "If enabled, user can delete themselves via FAPI.\n",
"nullable": true
},
"legal_accepted_at": {
"type": "string",
"description": "A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"skip_legal_checks": {
"type": "boolean",
"description": "When set to `true` all legal checks are skipped.\nIt is not recommended to skip legal checks unless you are migrating a user to Clerk.",
"nullable": true
},
"skip_user_requirement": {
"type": "boolean",
"description": "When set to `true`, identification types are not enforced.\nAt least one identification type must be enabled and provided on your instance (email, phone, web3 wallet, or username).\nUsers created without required identification types cannot use those authentication strategies\nIt is not recommended to use this flag unless you need to allow Clerk UI components to prompt for required fields while BAPI creates users with minimal data, or for migration a user to Clerk.",
"nullable": true
},
"create_organization_enabled": {
"type": "boolean",
"description": "If enabled, user can create organizations via FAPI.\n",
"nullable": true
},
"create_organizations_limit": {
"type": "integer",
"description": "The maximum number of organizations the user can create. 0 means unlimited.\n",
"nullable": true
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"bypass_client_trust": {
"type": "boolean",
"description": "When set to `true`, the user will bypass client trust checks during sign-in.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/count": {
"get": {
"operationId": "GetUsersCount",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "count",
"summary": "Count users",
"description": "Returns a total count of all users that match the given filtering criteria.",
"tags": [
"Users"
],
"parameters": [
{
"name": "email_address",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the specified email addresses.\nAccepts up to 100 email addresses.\nAny email addresses not found are ignored.",
"required": false
},
{
"name": "phone_number",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the specified phone numbers.\nAccepts up to 100 phone numbers.\nAny phone numbers not found are ignored.",
"required": false
},
{
"name": "external_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the specified external IDs.\nAccepts up to 100 external IDs.\nAny external IDs not found are ignored.",
"required": false
},
{
"name": "username",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored.",
"required": false
},
{
"name": "web3_wallet",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored.",
"required": false
},
{
"name": "user_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Counts users with the user IDs specified.\nAccepts up to 100 user IDs.\nAny user IDs not found are ignored.",
"required": false
},
{
"name": "organization_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"name": "query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "email_address_query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "phone_number_query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "username_query",
"in": "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.",
"schema": {
"type": "string"
}
},
{
"name": "name_query",
"in": "query",
"description": "Returns users with names that match the given query, via case-insensitive partial match.",
"schema": {
"type": "string"
}
},
{
"name": "banned",
"in": "query",
"required": false,
"description": "Counts users which are either banned (`banned=true`) or not banned (`banned=false`).",
"schema": {
"type": "boolean"
}
},
{
"name": "last_active_at_before",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_active_at_after",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_active_at_since",
"in": "query",
"deprecated": true,
"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`.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_before",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_after",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"name": "last_sign_in_at_before",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_sign_in_at_after",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "provider",
"in": "query",
"schema": {
"type": "string"
},
"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.",
"required": false
},
{
"name": "provider_user_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User.Count"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/{user_id}": {
"get": {
"operationId": "GetUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a user",
"description": "Retrieve the details of a user",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "update",
"summary": "Update a user",
"description": "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 they are optional in your instance settings and there's at least one other identifier which can be used for authentication.\n\nThis endpoint allows changing a user's password. When passing the `password` parameter directly you have two further options.\nYou can ignore the password policy checks for your instance by setting the `skip_password_checks` parameter to `true`.\nYou can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set `sign_out_of_other_sessions` to `true`.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"external_id": {
"type": "string",
"description": "The ID of the user as used in your external systems or your previous authentication solution.\nMust be unique across your instance.",
"nullable": true
},
"first_name": {
"type": "string",
"description": "The first name to assign to the user",
"nullable": true
},
"last_name": {
"type": "string",
"description": "The last name to assign to the user",
"nullable": true
},
"locale": {
"type": "string",
"description": "The locale to assign to the user (e.g., \"en-US\", \"fr-FR\")",
"nullable": true
},
"primary_email_address_id": {
"type": "string",
"description": "The ID of the email address to set as primary.\nIt must be verified, and present on the current user.",
"nullable": true
},
"notify_primary_email_address_changed": {
"type": "boolean",
"description": "If set to `true`, the user will be notified that their primary email address has changed.\nBy default, no notification is sent.",
"nullable": true,
"default": false
},
"primary_phone_number_id": {
"type": "string",
"description": "The ID of the phone number to set as primary.\nIt must be verified, and present on the current user.",
"nullable": true
},
"primary_web3_wallet_id": {
"type": "string",
"description": "The ID of the web3 wallets to set as primary.\nIt must be verified, and present on the current user.",
"nullable": true
},
"username": {
"type": "string",
"description": "The username to give to the user.\nIt must be unique across your instance.",
"nullable": true
},
"profile_image_id": {
"type": "string",
"description": "The ID of the image to set as the user's profile image",
"nullable": true
},
"password": {
"type": "string",
"description": "The plaintext password to give the user.\nMust be at least 8 characters long, and cannot be in any list of hacked passwords.",
"nullable": true
},
"password_digest": {
"type": "string",
"description": "In case you already have the password digests and not the passwords, you can use them for the newly created user via this property.\nThe digests should be generated with one of the supported algorithms.\nThe hashing algorithm can be specified using the `password_hasher` property."
},
"password_hasher": {
"$ref": "#/components/schemas/PasswordHasher"
},
"skip_password_checks": {
"type": "boolean",
"description": "Set it to `true` if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a `password`.",
"nullable": true
},
"sign_out_of_other_sessions": {
"type": "boolean",
"description": "Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`.",
"nullable": true
},
"totp_secret": {
"type": "string",
"description": "In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it.\nPlease note that currently the supported options are:\n* Period: 30 seconds\n* Code length: 6 digits\n* Algorithm: SHA1",
"nullable": true
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them.\nYou must provide the backup codes in plain format or the corresponding bcrypt digest."
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is visible to both your Frontend and Backend APIs",
"additionalProperties": true,
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is only visible to your Backend API",
"additionalProperties": true,
"nullable": true
},
"unsafe_metadata": {
"type": "object",
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe.",
"additionalProperties": true,
"nullable": true
},
"delete_self_enabled": {
"type": "boolean",
"description": "If true, the user can delete themselves with the Frontend API.",
"nullable": true
},
"create_organization_enabled": {
"type": "boolean",
"description": "If true, the user can create organizations with the Frontend API.",
"nullable": true
},
"legal_accepted_at": {
"type": "string",
"description": "A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"skip_legal_checks": {
"type": "boolean",
"description": "When set to `true` all legal checks are skipped.\nIt is not recommended to skip legal checks unless you are migrating a user to Clerk.",
"nullable": true
},
"create_organizations_limit": {
"type": "integer",
"description": "The maximum number of organizations the user can create. 0 means unlimited.",
"nullable": true
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"bypass_client_trust": {
"type": "boolean",
"description": "When set to `true`, the user will bypass client trust checks during sign-in.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "delete",
"summary": "Delete a user",
"description": "Delete the specified user",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/users/{user_id}/ban": {
"post": {
"operationId": "BanUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "ban",
"summary": "Ban a user",
"description": "Marks the given user as banned, which means that all their sessions are revoked and they are not allowed to sign in again.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to ban",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
}
},
"/users/{user_id}/unban": {
"post": {
"operationId": "UnbanUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "unban",
"summary": "Unban a user",
"description": "Removes the ban mark from the given user.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to unban",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
}
},
"/users/ban": {
"post": {
"operationId": "UsersBan",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "bulkBan",
"summary": "Ban multiple users",
"description": "Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again.",
"tags": [
"Users"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user_ids"
],
"properties": {
"user_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of user IDs to ban",
"minItems": 1,
"maxItems": 50
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
}
},
"/users/unban": {
"post": {
"operationId": "UsersUnban",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "bulkUnban",
"summary": "Unban multiple users",
"description": "Removes the ban mark from multiple users.",
"tags": [
"Users"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user_ids"
],
"properties": {
"user_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of user IDs to unban",
"minItems": 1,
"maxItems": 50
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
}
},
"/users/{user_id}/lock": {
"post": {
"operationId": "LockUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "lock",
"summary": "Lock a user",
"description": "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.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to lock",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
}
}
}
},
"/users/{user_id}/unlock": {
"post": {
"operationId": "UnlockUser",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "unlock",
"summary": "Unlock a user",
"description": "Removes the lock from the given user.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to unlock",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
}
}
}
},
"/users/{user_id}/profile_image": {
"post": {
"operationId": "SetUserProfileImage",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "setProfileImage",
"summary": "Set user profile image",
"description": "Update a user's profile image",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to update the profile image for",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ClerkErrors"
}
}
},
"delete": {
"operationId": "DeleteUserProfileImage",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deleteProfileImage",
"summary": "Delete user profile image",
"description": "Delete a user's profile image",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to delete the profile image for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"404": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/metadata": {
"patch": {
"operationId": "UpdateUserMetadata",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "updateMetadata",
"summary": "Merge and update a user's metadata",
"description": "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`.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose metadata will be updated and merged",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"public_metadata": {
"type": "object",
"additionalProperties": true,
"description": "Metadata saved on the user, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value."
},
"private_metadata": {
"type": "object",
"additionalProperties": true,
"description": "Metadata saved on the user that is only visible to your backend.\nThe new object will be merged with the existing value."
},
"unsafe_metadata": {
"type": "object",
"additionalProperties": true,
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nThe new object will be merged with the existing value.\n\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/{user_id}/billing/subscription": {
"get": {
"operationId": "GetUserBillingSubscription",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "getBillingSubscription",
"summary": "Retrieve a user's billing subscription",
"description": "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.",
"tags": [
"Users",
"Billing"
],
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the user whose subscription to retrieve"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/CommerceSubscription"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/oauth_access_tokens/{provider}": {
"get": {
"operationId": "GetOAuthAccessToken",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "getOAuthAccessToken",
"summary": "Retrieve the OAuth access token of a user",
"description": "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.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user for which to retrieve the OAuth access token",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "provider",
"in": "path",
"description": "The ID of the OAuth provider (e.g. `oauth_google`)",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OAuthAccessToken"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/{user_id}/organization_memberships": {
"get": {
"operationId": "UsersGetOrganizationMemberships",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "getOrganizationMemberships",
"summary": "Retrieve all memberships for a user",
"description": "Retrieve a paginated list of the user's organization memberships",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose organization memberships we want to retrieve",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMemberships"
},
"403": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/organization_invitations": {
"get": {
"operationId": "UsersGetOrganizationInvitations",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "getOrganizationInvitations",
"summary": "Retrieve all invitations for a user",
"description": "Retrieve a paginated list of the user's organization invitations",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose organization invitations we want to retrieve",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "status",
"description": "Filter organization invitations based on their status",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitationsWithPublicOrganizationData"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/users/{user_id}/verify_password": {
"post": {
"operationId": "VerifyPassword",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "verifyPassword",
"summary": "Verify the password of a user",
"description": "Check that the user's password matches the supplied input.\nUseful for custom auth flows and re-verification.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user for whom to verify the password",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"password": {
"type": "string",
"description": "The user password to verify"
}
},
"required": [
"password"
]
}
}
}
},
"responses": {
"200": {
"description": "The provided password was correct.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"verified": {
"type": "boolean",
"nullable": false
}
}
}
}
}
},
"400": {
"description": "The user does not have a password set."
},
"404": {
"description": "The user does not exist."
},
"422": {
"description": "The provided password was incorrect."
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/verify_totp": {
"post": {
"operationId": "VerifyTOTP",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "verifyTotp",
"summary": "Verify a TOTP or backup code for a user",
"description": "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.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user for whom to verify the TOTP",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "The TOTP or backup code to verify"
}
},
"required": [
"code"
]
}
}
}
},
"responses": {
"200": {
"description": "The provided TOTP or backup code was correct.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"verified": {
"type": "boolean",
"nullable": false
},
"code_type": {
"type": "string",
"nullable": false,
"enum": [
"totp",
"backup_code"
]
}
}
}
}
}
},
"400": {
"description": "The user does not have TOTP configured for their account."
},
"404": {
"description": "The user does not exist."
},
"422": {
"description": "The provided TOTP or backup code was incorrect."
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/mfa": {
"delete": {
"operationId": "DisableMFA",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "disableMfa",
"summary": "Disable a user's MFA methods",
"description": "Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose MFA methods are to be disabled",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"nullable": false
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/backup_code": {
"delete": {
"operationId": "DeleteBackupCode",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deleteBackupCodes",
"summary": "Disable all user's Backup codes",
"description": "Disable all of a user's backup codes.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose backup codes are to be deleted.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"nullable": false
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/passkeys/{passkey_identification_id}": {
"delete": {
"operationId": "UserPasskeyDelete",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deletePasskey",
"summary": "Delete a user passkey",
"description": "Delete the passkey identification for a given user and notify them through email.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user that owns the passkey identity",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "passkey_identification_id",
"in": "path",
"description": "The ID of the passkey identity to be deleted",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/web3_wallets/{web3_wallet_identification_id}": {
"delete": {
"operationId": "UserWeb3WalletDelete",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deleteWeb3Wallet",
"summary": "Delete a user web3 wallet",
"description": "Delete the web3 wallet identification for a given user.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user that owns the web3 wallet",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "web3_wallet_identification_id",
"in": "path",
"description": "The ID of the web3 wallet identity to be deleted",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/totp": {
"delete": {
"operationId": "DeleteTOTP",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deleteTOTP",
"summary": "Delete all the user's TOTPs",
"description": "Deletes all of the user's TOTPs.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user whose TOTPs are to be deleted",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Successful operation.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"nullable": false
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/external_accounts/{external_account_id}": {
"delete": {
"operationId": "DeleteExternalAccount",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "deleteExternalAccount",
"summary": "Delete External Account",
"description": "Delete an external account by ID.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user's external account",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "external_account_id",
"in": "path",
"description": "The ID of the external account to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/users/{user_id}/password/set_compromised": {
"post": {
"operationId": "SetUserPasswordCompromised",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "setPasswordCompromised",
"summary": "Set a user's password as compromised",
"description": "Sets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to set the password as compromised",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"revoke_all_sessions": {
"type": "boolean",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/users/{user_id}/password/unset_compromised": {
"post": {
"operationId": "UnsetUserPasswordCompromised",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "unsetPasswordCompromised",
"summary": "Unset a user's password as compromised",
"description": "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.",
"tags": [
"Users"
],
"parameters": [
{
"name": "user_id",
"in": "path",
"description": "The ID of the user to unset the compromised status for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/User"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/invitations": {
"post": {
"operationId": "CreateInvitation",
"x-speakeasy-group": "invitations",
"x-speakeasy-name-override": "create",
"summary": "Create an invitation",
"description": "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.",
"tags": [
"Invitations"
],
"requestBody": {
"description": "Required parameters",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"email_address": {
"type": "string",
"description": "The email address the invitation will be sent to"
},
"public_metadata": {
"type": "object",
"description": "Metadata that will be attached to the newly created invitation.\nThe value of this property should be a well-formed JSON object.\nOnce the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.",
"additionalProperties": true
},
"redirect_url": {
"type": "string",
"description": "Optional URL which specifies where to redirect the user once they click the invitation link.\nThis is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components."
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether an email invitation should be sent to the given email address.\nDefaults to `true`.",
"nullable": true,
"default": true
},
"ignore_existing": {
"type": "boolean",
"description": "Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.",
"nullable": true,
"default": false
},
"expires_in_days": {
"type": "integer",
"description": "The number of days the invitation will be valid for. By default, the invitation expires after 30 days.",
"nullable": true,
"minimum": 1,
"maximum": 365
},
"template_slug": {
"type": "string",
"enum": [
"invitation",
"waitlist_invitation"
],
"description": "The slug of the email template to use for the invitation email."
}
},
"required": [
"email_address"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Invitation"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"summary": "List all invitations",
"x-speakeasy-group": "invitations",
"x-speakeasy-name-override": "list",
"description": "Returns all non-revoked invitations for your application, sorted by creation date",
"operationId": "ListInvitations",
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"description": "Filter invitations based on their status",
"schema": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked",
"expired"
]
}
},
{
"in": "query",
"required": false,
"name": "query",
"description": "Filter invitations based on their `email_address` or `id`",
"schema": {
"type": "string"
}
},
{
"name": "order_by",
"in": "query",
"required": false,
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"tags": [
"Invitations"
],
"responses": {
"200": {
"$ref": "#/components/responses/Invitation.List"
}
}
}
},
"/invitations/bulk": {
"post": {
"operationId": "CreateBulkInvitations",
"x-speakeasy-group": "invitations",
"x-speakeasy-name-override": "bulkCreate",
"summary": "Create multiple invitations",
"description": "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 maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.",
"tags": [
"Invitations"
],
"requestBody": {
"description": "Required parameters",
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"email_address": {
"type": "string",
"description": "The email address the invitation will be sent to"
},
"public_metadata": {
"type": "object",
"nullable": true,
"description": "Metadata that will be attached to the newly created invitation.\nThe value of this property should be a well-formed JSON object.\nOnce the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.",
"additionalProperties": true
},
"redirect_url": {
"type": "string",
"nullable": true,
"description": "The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations)."
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether an email invitation should be sent to the given email address.\nDefaults to true.",
"nullable": true,
"default": true
},
"ignore_existing": {
"type": "boolean",
"description": "Whether an invitation should be created if there is already an existing invitation for this email\naddress, or it's claimed by another user.",
"nullable": true,
"default": false
},
"expires_in_days": {
"type": "integer",
"description": "The number of days the invitation will be valid for. By default, the invitation expires after 30 days.",
"nullable": true,
"minimum": 1,
"maximum": 365
},
"template_slug": {
"type": "string",
"enum": [
"invitation",
"waitlist_invitation"
],
"description": "The slug of the email template to use for the invitation email.",
"default": "invitation"
}
},
"required": [
"email_address"
]
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Invitation.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/invitations/{invitation_id}/revoke": {
"post": {
"operationId": "RevokeInvitation",
"x-speakeasy-group": "invitations",
"x-speakeasy-name-override": "revoke",
"summary": "Revokes an invitation",
"description": "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.",
"tags": [
"Invitations"
],
"parameters": [
{
"name": "invitation_id",
"in": "path",
"description": "The ID of the invitation to be revoked",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Invitation.Revoked"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organization_invitations": {
"get": {
"operationId": "ListInstanceOrganizationInvitations",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "getAll",
"summary": "Get a list of organization invitations for the current instance",
"description": "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 date by default.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "query",
"name": "order_by",
"required": false,
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"in": "query",
"name": "status",
"description": "Filter organization invitations based on their status",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked"
]
}
},
{
"in": "query",
"required": false,
"name": "query",
"description": "Filter organization invitations based on their `email_address`",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitationsWithPublicOrganizationData"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/ClerkErrors"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/allowlist_identifiers": {
"get": {
"operationId": "ListAllowlistIdentifiers",
"x-speakeasy-group": "allowlistIdentifiers",
"x-speakeasy-name-override": "list",
"summary": "List all identifiers on the allow-list",
"description": "Get a list of all identifiers allowed to sign up to an instance",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"tags": [
"Allow-list / Block-list"
],
"responses": {
"200": {
"$ref": "#/components/responses/AllowlistIdentifier.List"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
},
"post": {
"operationId": "CreateAllowlistIdentifier",
"x-speakeasy-group": "allowlistIdentifiers",
"x-speakeasy-name-override": "create",
"summary": "Add identifier to the allow-list",
"description": "Create an identifier allowed to sign up to an instance",
"tags": [
"Allow-list / Block-list"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"identifier": {
"type": "string",
"description": "The identifier to be added in the allow-list.\nThis can be an email address, a phone number, or a web3 wallet."
},
"notify": {
"type": "boolean",
"description": "This flag denotes whether the given identifier will receive an invitation to join the application.\nNote that this only works for email address and phone number identifiers.",
"default": false
}
},
"required": [
"identifier"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/AllowlistIdentifier"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/allowlist_identifiers/{identifier_id}": {
"delete": {
"operationId": "DeleteAllowlistIdentifier",
"x-speakeasy-group": "allowlistIdentifiers",
"x-speakeasy-name-override": "delete",
"summary": "Delete identifier from allow-list",
"description": "Delete an identifier from the instance allow-list",
"tags": [
"Allow-list / Block-list"
],
"parameters": [
{
"name": "identifier_id",
"in": "path",
"description": "The ID of the identifier to delete from the allow-list",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/blocklist_identifiers": {
"get": {
"operationId": "ListBlocklistIdentifiers",
"x-speakeasy-group": "blocklistIdentifiers",
"x-speakeasy-name-override": "list",
"summary": "List all identifiers on the block-list",
"description": "Get a list of all identifiers which are not allowed to access an instance",
"tags": [
"Allow-list / Block-list"
],
"responses": {
"200": {
"$ref": "#/components/responses/BlocklistIdentifier.List"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
}
}
},
"post": {
"operationId": "CreateBlocklistIdentifier",
"x-speakeasy-group": "blocklistIdentifiers",
"x-speakeasy-name-override": "create",
"summary": "Add identifier to the block-list",
"description": "Create an identifier that is blocked from accessing an instance",
"tags": [
"Allow-list / Block-list"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"identifier": {
"type": "string",
"description": "The identifier to be added in the block-list.\nThis can be an email address, a phone number, or a web3 wallet."
}
},
"required": [
"identifier"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/BlocklistIdentifier"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/blocklist_identifiers/{identifier_id}": {
"delete": {
"operationId": "DeleteBlocklistIdentifier",
"x-speakeasy-group": "blocklistIdentifiers",
"x-speakeasy-name-override": "delete",
"summary": "Delete identifier from block-list",
"description": "Delete an identifier from the instance block-list",
"tags": [
"Allow-list / Block-list"
],
"parameters": [
{
"name": "identifier_id",
"in": "path",
"description": "The ID of the identifier to delete from the block-list",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/beta_features/instance_settings": {
"patch": {
"operationId": "UpdateInstanceAuthConfig",
"x-speakeasy-group": "betaFeatures",
"x-speakeasy-name-override": "updateInstanceSettings",
"summary": "Update instance settings",
"description": "Updates the settings of an instance",
"tags": [
"Beta Features"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"restricted_to_allowlist": {
"type": "boolean",
"description": "Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist.",
"nullable": true,
"default": false
},
"from_email_address": {
"type": "string",
"description": "The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent.\nOnly alphanumeric values are allowed.\nNote that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`).",
"nullable": true
},
"progressive_sign_up": {
"type": "boolean",
"description": "Enable the Progressive Sign Up algorithm. This feature is deprecated, please contact support if you need assistance.",
"nullable": true
},
"test_mode": {
"type": "boolean",
"description": "Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.\nDefaults to true for development instances.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/InstanceSettings"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/beta_features/domain": {
"put": {
"deprecated": true,
"operationId": "UpdateProductionInstanceDomain",
"x-speakeasy-group": "betaFeatures",
"x-speakeasy-name-override": "updateProductionInstanceDomain",
"summary": "Update production instance domain",
"description": "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 deployed, a small downtime is expected to occur.",
"tags": [
"Beta Features"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"home_url": {
"type": "string",
"description": "The new home URL of the production instance e.g. https://www.example.com"
},
"is_secondary": {
"type": "boolean",
"description": "Whether the domain is a secondary app."
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/actor_tokens": {
"post": {
"operationId": "CreateActorToken",
"x-speakeasy-group": "actorTokens",
"x-speakeasy-name-override": "create",
"summary": "Create actor token",
"description": "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.",
"tags": [
"Actor Tokens"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"description": "The ID of the user being impersonated."
},
"actor": {
"type": "object",
"additionalProperties": true,
"description": "The actor payload. It needs to include a sub property which should contain the ID of the actor.\nThis whole payload will be also included in the JWT session token.",
"properties": {
"sub": {
"type": "string",
"description": "The ID of the actor."
}
},
"required": [
"sub"
],
"example": {
"sub": "user_2OEpKhcCN1Lat9NQ0G6puh7q5Rb"
}
},
"expires_in_seconds": {
"type": "integer",
"description": "Optional parameter to specify the life duration of the actor token in seconds.\nBy default, the duration is 1 hour.",
"default": 3600
},
"session_max_duration_in_seconds": {
"type": "integer",
"description": "The maximum duration that the session which will be created by the generated actor token should last.\nBy default, the duration of a session created via an actor token, lasts 30 minutes.",
"default": 1800
}
},
"required": [
"user_id",
"actor"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/ActorToken"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/actor_tokens/{actor_token_id}/revoke": {
"post": {
"x-speakeasy-group": "actorTokens",
"x-speakeasy-name-override": "revoke",
"summary": "Revoke actor token",
"description": "Revokes a pending actor token.",
"operationId": "RevokeActorToken",
"tags": [
"Actor Tokens"
],
"parameters": [
{
"name": "actor_token_id",
"in": "path",
"description": "The ID of the actor token to be revoked.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/ActorToken"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/domains": {
"get": {
"operationId": "ListDomains",
"x-speakeasy-group": "domains",
"x-speakeasy-name-override": "list",
"summary": "List all instance domains",
"description": "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.",
"tags": [
"Domains"
],
"responses": {
"200": {
"$ref": "#/components/responses/Domains"
}
}
},
"post": {
"summary": "Add a domain",
"operationId": "AddDomain",
"x-speakeasy-group": "domains",
"x-speakeasy-name-override": "add",
"description": "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.",
"tags": [
"Domains"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The new domain name. Can contain the port for development instances."
},
"is_satellite": {
"type": "boolean",
"description": "Marks the new domain as satellite. Only `true` is accepted at the moment.",
"enum": [
true
]
},
"proxy_url": {
"type": "string",
"description": "The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances.",
"nullable": true
}
},
"required": [
"name",
"is_satellite"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Domain"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/domains/{domain_id}": {
"delete": {
"operationId": "DeleteDomain",
"x-speakeasy-group": "domains",
"x-speakeasy-name-override": "delete",
"summary": "Delete a satellite domain",
"description": "Deletes a satellite domain for the instance.\nIt is currently not possible to delete the instance's primary domain.",
"tags": [
"Domains"
],
"parameters": [
{
"in": "path",
"name": "domain_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the domain that will be deleted. Must be a satellite domain."
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"403": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateDomain",
"x-speakeasy-group": "domains",
"x-speakeasy-name-override": "update",
"summary": "Update a domain",
"description": "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\nemails to work. Expect downtime otherwise. Updating a primary domain's name will also\nupdate the instance's home origin, affecting the default application paths.",
"tags": [
"Domains"
],
"parameters": [
{
"in": "path",
"name": "domain_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the domain that will be updated."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The new domain name. For development instances, can contain the port,\ni.e `myhostname:3000`. For production instances, must be a valid FQDN,\ni.e `mysite.com`. Cannot contain protocol scheme.",
"nullable": true
},
"proxy_url": {
"type": "string",
"description": "The full URL of the proxy that will forward requests to Clerk's Frontend API.\nCan only be updated for production instances.",
"nullable": true
},
"is_secondary": {
"type": "boolean",
"description": "Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and\nwill be stored as part of the domain. This is useful for supporting multiple apps (one primary and\nmultiple secondaries) on the same root domain (eTLD+1).",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Domain"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/instance": {
"get": {
"operationId": "GetInstance",
"x-speakeasy-group": "instanceSettings",
"x-speakeasy-name-override": "get",
"summary": "Fetch the current instance",
"description": "Fetches the current instance",
"tags": [
"Instance Settings"
],
"responses": {
"200": {
"$ref": "#/components/responses/Instance"
}
}
},
"patch": {
"operationId": "UpdateInstance",
"x-speakeasy-group": "instanceSettings",
"x-speakeasy-name-override": "update",
"summary": "Update instance settings",
"description": "Updates the settings of an instance",
"tags": [
"Instance Settings"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"test_mode": {
"type": "boolean",
"description": "Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.\nDefaults to true for development instances.",
"nullable": true
},
"hibp": {
"type": "boolean",
"description": "Whether the instance should be using the HIBP service to check passwords for breaches",
"nullable": true
},
"support_email": {
"type": "string",
"nullable": true
},
"clerk_js_version": {
"type": "string",
"nullable": true
},
"development_origin": {
"type": "string",
"nullable": true
},
"allowed_origins": {
"type": "array",
"items": {
"type": "string"
},
"description": "For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uuid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost."
},
"cookieless_dev": {
"type": "boolean",
"description": "Whether the instance should operate in cookieless development mode (i.e. without third-party cookies).\nDeprecated: Please use `url_based_session_syncing` instead.",
"deprecated": true,
"nullable": true
},
"url_based_session_syncing": {
"type": "boolean",
"description": "Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies).",
"nullable": true
}
}
}
}
}
},
"responses": {
"204": {
"description": "Accepted"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/instance/restrictions": {
"patch": {
"operationId": "UpdateInstanceRestrictions",
"x-speakeasy-group": "instanceSettings",
"x-speakeasy-name-override": "updateRestrictions",
"summary": "Update instance restrictions",
"description": "Updates the restriction settings of an instance",
"tags": [
"Instance Settings"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"allowlist": {
"type": "boolean",
"nullable": true
},
"blocklist": {
"type": "boolean",
"nullable": true
},
"allowlist_blocklist_disabled_on_sign_in": {
"type": "boolean",
"nullable": true
},
"block_email_subaddresses": {
"type": "boolean",
"nullable": true
},
"block_disposable_email_domains": {
"type": "boolean",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/InstanceRestrictions"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/instance/protect": {
"get": {
"operationId": "GetInstanceProtect",
"summary": "Get instance protect settings",
"tags": [
"Instance Settings"
],
"responses": {
"200": {
"$ref": "#/components/responses/InstanceProtect"
}
}
},
"patch": {
"operationId": "UpdateInstanceProtect",
"summary": "Update instance protect settings",
"tags": [
"Instance Settings"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"rules_enabled": {
"type": "boolean",
"nullable": true
},
"specter_enabled": {
"type": "boolean",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/InstanceProtect"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/instance/change_domain": {
"post": {
"operationId": "ChangeProductionInstanceDomain",
"x-speakeasy-group": "instanceSettings",
"x-speakeasy-name-override": "changeDomain",
"summary": "Update production instance domain",
"description": "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 deployed, a small downtime is expected to occur.",
"tags": [
"Beta Features"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"home_url": {
"type": "string",
"description": "The new home URL of the production instance e.g. https://www.example.com"
},
"is_secondary": {
"type": "boolean",
"description": "Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and\nwill be stored as part of the domain. This is useful for supporting multiple apps (one primary and\nmultiple secondaries) on the same root domain (eTLD+1)."
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/instance/organization_settings": {
"patch": {
"operationId": "UpdateInstanceOrganizationSettings",
"x-speakeasy-group": "instanceSettings",
"x-speakeasy-name-override": "updateOrganizationSettings",
"summary": "Update instance organization settings",
"description": "Updates the organization settings of the instance",
"tags": [
"Instance Settings"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean",
"nullable": true
},
"max_allowed_memberships": {
"type": "integer",
"nullable": true
},
"admin_delete_enabled": {
"type": "boolean",
"nullable": true
},
"domains_enabled": {
"type": "boolean",
"nullable": true
},
"slug_disabled": {
"type": "boolean",
"nullable": true
},
"domains_enrollment_modes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Specify which enrollment modes to enable for your Organization Domains.\nSupported modes are 'automatic_invitation' & 'automatic_suggestion'."
},
"creator_role_id": {
"type": "string",
"description": "Specify what the default organization role is for an organization creator.",
"nullable": true
},
"domains_default_role_id": {
"type": "string",
"description": "Specify what the default organization role is for the organization domains.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationSettings"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/webhooks/svix": {
"post": {
"operationId": "CreateSvixApp",
"x-speakeasy-group": "webhooks",
"x-speakeasy-name-override": "createSvixApp",
"summary": "Create a Svix app",
"description": "Create a Svix app and associate it with the current instance",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"$ref": "#/components/responses/SvixURL"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
}
}
},
"delete": {
"operationId": "DeleteSvixApp",
"x-speakeasy-group": "webhooks",
"x-speakeasy-name-override": "deleteSvixApp",
"summary": "Delete a Svix app",
"description": "Delete a Svix app and disassociate it from the current instance",
"tags": [
"Webhooks"
],
"responses": {
"204": {
"description": "Svix app was successfully deleted"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/webhooks/svix_url": {
"post": {
"operationId": "GenerateSvixAuthURL",
"x-speakeasy-group": "webhooks",
"x-speakeasy-name-override": "generateSvixAuthURL",
"summary": "Create a Svix Dashboard URL",
"description": "Generate a new URL for accessing the Svix's management dashboard for that particular instance",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"$ref": "#/components/responses/SvixURL"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/jwt_templates": {
"get": {
"operationId": "ListJWTTemplates",
"x-speakeasy-group": "jwtTemplates",
"x-speakeasy-name-override": "list",
"summary": "List all templates",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"tags": [
"JWT Templates"
],
"responses": {
"200": {
"$ref": "#/components/responses/JWTTemplate.List"
}
}
},
"post": {
"operationId": "CreateJWTTemplate",
"x-speakeasy-group": "jwtTemplates",
"x-speakeasy-name-override": "create",
"summary": "Create a JWT template",
"description": "Create a new JWT template",
"tags": [
"JWT Templates"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "JWT template name",
"nullable": false
},
"claims": {
"type": "object",
"description": "JWT template claims in JSON format",
"nullable": false
},
"lifetime": {
"type": "integer",
"minimum": 30,
"maximum": 315360000,
"description": "JWT lifetime",
"nullable": true
},
"allowed_clock_skew": {
"type": "integer",
"minimum": 0,
"maximum": 300,
"description": "JWT allowed clock skew",
"nullable": true
},
"custom_signing_key": {
"type": "boolean",
"description": "Whether a custom signing key/algorithm is also provided for this template"
},
"signing_algorithm": {
"type": "string",
"description": "The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`.",
"nullable": true
},
"signing_key": {
"type": "string",
"description": "The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`.",
"nullable": true
}
},
"required": [
"name",
"claims"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/JWTTemplate"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/jwt_templates/{template_id}": {
"get": {
"operationId": "GetJWTTemplate",
"x-speakeasy-group": "jwtTemplates",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a template",
"description": "Retrieve the details of a given JWT template",
"tags": [
"JWT Templates"
],
"parameters": [
{
"name": "template_id",
"in": "path",
"description": "JWT Template ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/JWTTemplate"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateJWTTemplate",
"x-speakeasy-group": "jwtTemplates",
"x-speakeasy-name-override": "update",
"summary": "Update a JWT template",
"description": "Updates an existing JWT template",
"tags": [
"JWT Templates"
],
"parameters": [
{
"name": "template_id",
"in": "path",
"description": "The ID of the JWT template to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "JWT template name",
"nullable": false
},
"claims": {
"type": "object",
"description": "JWT template claims in JSON format",
"nullable": false
},
"lifetime": {
"type": "integer",
"minimum": 30,
"maximum": 315360000,
"description": "JWT lifetime",
"nullable": true
},
"allowed_clock_skew": {
"type": "integer",
"minimum": 0,
"maximum": 300,
"description": "JWT allowed clock skew",
"nullable": true
},
"custom_signing_key": {
"type": "boolean",
"description": "Whether a custom signing key/algorithm is also provided for this template"
},
"signing_algorithm": {
"type": "string",
"description": "The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`.",
"nullable": true
},
"signing_key": {
"type": "string",
"description": "The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`.",
"nullable": true
}
},
"required": [
"name",
"claims"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/JWTTemplate"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteJWTTemplate",
"x-speakeasy-group": "jwtTemplates",
"x-speakeasy-name-override": "delete",
"summary": "Delete a Template",
"description": "",
"tags": [
"JWT Templates"
],
"parameters": [
{
"name": "template_id",
"in": "path",
"description": "JWT Template ID",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/machine_tokens": {
},
"/machines": {
"get": {
"operationId": "ListMachines",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "list",
"summary": "Get a list of machines for an instance",
"description": "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)",
"tags": [
"Machines"
],
"parameters": [
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "query",
"description": "Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name.",
"schema": {
"type": "string"
},
"allowEmptyValue": true,
"required": false
},
{
"in": "query",
"name": "order_by",
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
},
"required": false
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Machine.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateMachine",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "create",
"summary": "Create a machine",
"description": "Creates a new machine.",
"tags": [
"Machines"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the machine",
"minLength": 1,
"maxLength": 255
},
"scoped_machines": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of machine IDs that this machine will have access to. Maximum of 150 scopes per machine.",
"maxItems": 150
},
"default_token_ttl": {
"type": "integer",
"description": "The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.",
"minimum": 1,
"maximum": 315360000,
"default": 3600
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Machine.Created"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/machines/{machine_id}": {
"get": {
"operationId": "GetMachine",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a machine",
"description": "Returns the details of a machine.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Machine"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"patch": {
"operationId": "UpdateMachine",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "update",
"summary": "Update a machine",
"description": "Updates an existing machine.\nOnly the provided fields will be updated.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the machine",
"minLength": 1,
"maxLength": 255
},
"default_token_ttl": {
"type": "integer",
"description": "The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second.",
"minimum": 1,
"maximum": 315360000
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Machine"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteMachine",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "delete",
"summary": "Delete a machine",
"description": "Deletes a machine.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Machine.Deleted"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/machines/{machine_id}/secret_key": {
"get": {
"operationId": "GetMachineSecretKey",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "getSecretKey",
"summary": "Retrieve a machine secret key",
"description": "Returns the secret key for a machine.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine to retrieve the secret key for",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Machine.SecretKey"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/machines/{machine_id}/secret_key/rotate": {
"post": {
"operationId": "RotateMachineSecretKey",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "rotateSecretKey",
"summary": "Rotate a machine's secret key",
"description": "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.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine to rotate the secret key for",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"previous_token_ttl"
],
"properties": {
"previous_token_ttl": {
"type": "integer",
"minimum": 0,
"maximum": 28800,
"description": "The time in seconds that the previous secret key will remain valid after rotation.\nThis ensures a graceful transition period for updating applications with the new secret key.\nSet to 0 to immediately expire the previous key. Maximum value is 8 hours (28800 seconds)."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Machine.SecretKey"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/machines/{machine_id}/scopes": {
"post": {
"operationId": "CreateMachineScope",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "createScope",
"summary": "Create a machine scope",
"description": "Creates a new machine scope, allowing the specified machine to access another machine.\nMaximum of 150 scopes per machine.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine that will have access to another machine",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"to_machine_id"
],
"properties": {
"to_machine_id": {
"type": "string",
"description": "The ID of the machine that will be scoped to the current machine"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/MachineScope"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/machines/{machine_id}/scopes/{other_machine_id}": {
"delete": {
"operationId": "DeleteMachineScope",
"x-speakeasy-group": "machines",
"x-speakeasy-name-override": "deleteScope",
"summary": "Delete a machine scope",
"description": "Deletes a machine scope, removing access from one machine to another.",
"tags": [
"Machines"
],
"parameters": [
{
"name": "machine_id",
"in": "path",
"description": "The ID of the machine that has access to another machine",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "other_machine_id",
"in": "path",
"description": "The ID of the machine that is being accessed",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/MachineScope.Deleted"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations": {
"get": {
"operationId": "ListOrganizations",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "list",
"summary": "Get a list of organizations for an instance",
"description": "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.",
"tags": [
"Organizations"
],
"parameters": [
{
"in": "query",
"required": false,
"name": "include_members_count",
"description": "Flag to denote whether the member counts of each organization should be included in the response or not.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"required": false,
"name": "include_missing_member_with_elevated_permissions",
"description": "Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"required": false,
"name": "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.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "user_id",
"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.",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false
},
{
"in": "query",
"name": "organization_id",
"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",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false
},
{
"in": "query",
"name": "order_by",
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
},
"required": false
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Organizations"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateOrganization",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "create",
"summary": "Create an organization",
"description": "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 Backend API.\nPublic metadata can be accessed from the Backend API, and are read-only from the Frontend API.\nThe `created_by` user will see this as their [active organization](https://clerk.com/docs/organizations/overview#active-organization)\nthe next time they create a session, presuming they don't explicitly set a different organization as active before then.",
"tags": [
"Organizations"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the new organization.\nMay not contain URLs or HTML.\nMax length: 256"
},
"created_by": {
"type": "string",
"description": "The ID of the User who will become the administrator for the new organization",
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization, accessible only from the Backend API",
"additionalProperties": true,
"nullable": true
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API",
"additionalProperties": true,
"nullable": true
},
"slug": {
"type": "string",
"description": "A slug for the new organization.\nCan contain only lowercase alphanumeric characters and the dash \"-\".\nMust be unique for the instance.\nThis field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs).",
"nullable": true
},
"max_allowed_memberships": {
"type": "integer",
"minimum": 0,
"description": "The maximum number of memberships allowed for this organization",
"nullable": true
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"role_set_key": {
"type": "string",
"description": "The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.",
"nullable": true
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Organization"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}": {
"get": {
"operationId": "GetOrganization",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "get",
"summary": "Retrieve an organization by ID or slug",
"description": "Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter.",
"tags": [
"Organizations"
],
"parameters": [
{
"in": "path",
"name": "organization_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID or slug of the organization"
},
{
"in": "query",
"required": false,
"name": "include_members_count",
"description": "Flag to denote whether or not the organization's members count should be included in the response.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"required": false,
"name": "include_missing_member_with_elevated_permissions",
"description": "Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.",
"schema": {
"type": "boolean"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Organization"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateOrganization",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "update",
"summary": "Update an organization",
"description": "Updates an existing organization",
"tags": [
"Organizations"
],
"parameters": [
{
"in": "path",
"name": "organization_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the organization to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, that is visible to both your frontend and backend.",
"additionalProperties": true,
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization that is only visible to your backend.",
"additionalProperties": true,
"nullable": true
},
"name": {
"type": "string",
"description": "The new name of the organization.\nMay not contain URLs or HTML.\nMax length: 256",
"nullable": true
},
"slug": {
"type": "string",
"description": "The new slug of the organization, which needs to be unique in the instance",
"nullable": true
},
"max_allowed_memberships": {
"type": "integer",
"minimum": 0,
"description": "The maximum number of memberships allowed for this organization",
"nullable": true
},
"admin_delete_enabled": {
"type": "boolean",
"description": "If true, an admin can delete this organization with the Frontend API.",
"nullable": true
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).",
"nullable": true
},
"role_set_key": {
"type": "string",
"description": "The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Organization"
},
"402": {
"$ref": "#/components/responses/ResourceNotFound"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOrganization",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "delete",
"summary": "Delete an organization",
"description": "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.",
"tags": [
"Organizations"
],
"parameters": [
{
"in": "path",
"name": "organization_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the organization to delete"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organizations/{organization_id}/metadata": {
"patch": {
"operationId": "MergeOrganizationMetadata",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "mergeMetadata",
"summary": "Merge and update metadata for an organization",
"description": "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`.",
"tags": [
"Organizations"
],
"parameters": [
{
"name": "organization_id",
"in": "path",
"description": "The ID of the organization for which metadata will be merged or updated",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value.",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization that is only visible to your backend.\nThe new object will be merged with the existing value.",
"additionalProperties": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Organization"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/logo": {
"put": {
"operationId": "UploadOrganizationLogo",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "uploadLogo",
"summary": "Upload a logo for the organization",
"description": "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`.",
"tags": [
"Organizations"
],
"parameters": [
{
"name": "organization_id",
"in": "path",
"description": "The ID of the organization for which to upload a logo",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"uploader_user_id": {
"type": "string",
"description": "The ID of the user that will be credited with the image upload."
},
"file": {
"type": "string",
"format": "binary"
}
},
"required": [
"file"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationWithLogo"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"413": {
"$ref": "#/components/responses/ClerkErrors"
}
}
},
"delete": {
"operationId": "DeleteOrganizationLogo",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "deleteLogo",
"summary": "Delete the organization's logo.",
"description": "Delete the organization's logo.",
"tags": [
"Organizations"
],
"parameters": [
{
"name": "organization_id",
"in": "path",
"description": "The ID of the organization for which the logo will be deleted.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Organization"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organizations/{organization_id}/billing/subscription": {
"get": {
"operationId": "GetOrganizationBillingSubscription",
"x-speakeasy-group": "organizations",
"x-speakeasy-name-override": "getBillingSubscription",
"summary": "Retrieve an organization's billing subscription",
"description": "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.",
"tags": [
"Organizations",
"Billing"
],
"parameters": [
{
"in": "path",
"name": "organization_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the organization whose subscription to retrieve"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/CommerceSubscription"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/organizations/{organization_id}/invitations": {
"post": {
"operationId": "CreateOrganizationInvitation",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "create",
"summary": "Create and send an organization invitation",
"description": "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 be redirected to the URL provided.\nUse this parameter to implement a custom invitation acceptance flow.\n\nYou can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter.\nThat user must be a member with administrator privileges in the organization.\nOnly \"admin\" members can create organization invitations.\n\nYou can optionally provide public and private metadata for the organization invitation.\nThe public metadata are visible by both the Frontend and the Backend whereas the private ones only by the Backend.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization for which to send the invitation"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email_address": {
"type": "string",
"description": "The email address of the new member that is going to be invited to the organization"
},
"inviter_user_id": {
"type": "string",
"nullable": true,
"description": "The ID of the user that invites the new member to the organization.\nMust be an administrator in the organization."
},
"role": {
"type": "string",
"description": "The role of the new member in the organization"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"additionalProperties": true,
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"additionalProperties": true,
"nullable": true
},
"redirect_url": {
"type": "string",
"description": "Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.",
"nullable": true
},
"expires_in_days": {
"type": "integer",
"description": "The number of days the invitation will be valid for. By default, the invitation has a 30 days expire.",
"nullable": true,
"minimum": 1,
"maximum": 365
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether an email invitation should be sent to the given email address.\nDefaults to `true`.",
"nullable": true,
"default": true
}
},
"required": [
"email_address",
"role"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitation"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"operationId": "ListOrganizationInvitations",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "list",
"summary": "Get a list of organization invitations",
"description": "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.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"in": "query",
"name": "status",
"description": "Filter organization invitations based on their status",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked"
]
}
},
{
"in": "query",
"required": false,
"name": "email_address",
"description": "Returns organization invitations inviting the specified email address.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "order_by",
"required": false,
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitations"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/invitations/bulk": {
"post": {
"operationId": "CreateOrganizationInvitationBulk",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "bulkCreate",
"summary": "Bulk create and send organization invitations",
"description": "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 the invitee.\nThe request body supports passing an optional `redirect_url` parameter for each invitation.\nWhen the invited user clicks the link to accept the invitation, they will be redirected to the provided URL.\nUse this parameter to implement a custom invitation acceptance flow.\nYou can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. Each invitation\ncan have a different inviter user.\nInviter users must be members with administrator privileges in the organization.\nOnly \"admin\" members can create organization invitations.\nYou can optionally provide public and private metadata for each organization invitation. The public metadata are visible\nby both the Frontend and the Backend, whereas the private metadata are only visible by the Backend.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"email_address": {
"type": "string",
"description": "The email address of the new member that is going to be invited to the organization"
},
"inviter_user_id": {
"type": "string",
"nullable": true,
"description": "The ID of the user that invites the new member to the organization.\nMust be an administrator in the organization."
},
"role": {
"type": "string",
"description": "The role of the new member in the organization"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"additionalProperties": true,
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.\nWhen the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.",
"additionalProperties": true,
"nullable": true
},
"redirect_url": {
"type": "string",
"description": "Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.",
"nullable": true
},
"expires_in_days": {
"type": "integer",
"description": "The number of days the invitation will be valid for. By default, the invitation has a 30 days expire.",
"nullable": true,
"minimum": 1,
"maximum": 365
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether an email invitation should be sent to the given email address.\nDefaults to `true`.",
"nullable": true,
"default": true
}
},
"required": [
"email_address",
"role"
]
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitations"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/invitations/pending": {
"get": {
"deprecated": true,
"operationId": "ListPendingOrganizationInvitations",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "listPending",
"summary": "Get a list of pending organization invitations",
"description": "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 in the results.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitations"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organizations/{organization_id}/invitations/{invitation_id}": {
"get": {
"operationId": "GetOrganizationInvitation",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "get",
"summary": "Retrieve an organization invitation by ID",
"description": "Use this request to get an existing organization invitation by ID.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"in": "path",
"required": true,
"name": "invitation_id",
"schema": {
"type": "string"
},
"description": "The organization invitation ID."
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitation"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organizations/{organization_id}/invitations/{invitation_id}/revoke": {
"post": {
"operationId": "RevokeOrganizationInvitation",
"x-speakeasy-group": "organizationInvitations",
"x-speakeasy-name-override": "revoke",
"summary": "Revoke a pending organization invitation",
"description": "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.",
"tags": [
"Organization Invitations"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"in": "path",
"required": true,
"name": "invitation_id",
"schema": {
"type": "string"
},
"description": "The organization invitation ID."
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"requesting_user_id": {
"type": "string",
"nullable": true,
"description": "The ID of the user that revokes the invitation.\nMust be an administrator in the organization."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationInvitation"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organization_roles": {
"get": {
"operationId": "ListOrganizationRoles",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "list",
"summary": "Get a list of organization roles",
"description": "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.",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "query",
"name": "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.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "order_by",
"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`.",
"required": false,
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Roles"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "create",
"summary": "Create an organization role",
"description": "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.",
"tags": [
"Organization Roles"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the new organization role"
},
"key": {
"type": "string",
"description": "A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores."
},
"description": {
"type": "string",
"description": "Optional description for the role",
"nullable": true
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of permission IDs to assign to the role",
"nullable": true
},
"include_in_initial_role_set": {
"type": "boolean",
"description": "Whether this role should be included in the initial role set",
"nullable": true
}
},
"additionalProperties": false,
"required": [
"name",
"key"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Role"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organization_roles/{organization_role_id}": {
"get": {
"operationId": "GetOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "get",
"summary": "Retrieve an organization role",
"description": "Use this request to retrieve an existing organization role by its ID.",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_role_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization role"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Role"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "update",
"summary": "Update an organization role",
"description": "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.",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_role_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization role to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The new name for the organization role",
"nullable": true
},
"key": {
"type": "string",
"description": "A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores.",
"nullable": true
},
"description": {
"type": "string",
"description": "Optional description for the role",
"nullable": true
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of permission IDs to assign to the role. If provided, this will replace the existing permissions.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Role"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "delete",
"summary": "Delete an organization role",
"description": "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.",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_role_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization role to delete"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organization_roles/{organization_role_id}/permissions/{permission_id}": {
"post": {
"operationId": "AssignPermissionToOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "assignPermission",
"summary": "Assign a permission to an organization role",
"description": "Assigns a permission to an organization role",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_role_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization role"
},
{
"in": "path",
"required": true,
"name": "permission_id",
"schema": {
"type": "string"
},
"description": "The ID of the permission to assign"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Role"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
}
}
},
"delete": {
"operationId": "RemovePermissionFromOrganizationRole",
"x-speakeasy-group": "organizationRoles",
"x-speakeasy-name-override": "removePermission",
"summary": "Remove a permission from an organization role",
"description": "Removes a permission from an organization role",
"tags": [
"Organization Roles"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_role_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization role"
},
{
"in": "path",
"required": true,
"name": "permission_id",
"schema": {
"type": "string"
},
"description": "The ID of the permission to remove"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Role"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/memberships": {
"post": {
"operationId": "CreateOrganizationMembership",
"x-speakeasy-group": "organizationMemberships",
"x-speakeasy-name-override": "create",
"summary": "Create a new organization membership",
"description": "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.",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization where the new membership will be created"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The ID of the user that will be added as a member in the organization.\nThe user needs to exist in the same instance as the organization and must not be a member of the given organization already."
},
"role": {
"type": "string",
"description": "The role that the new member will have in the organization."
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, that is visible to both your frontend and backend.",
"additionalProperties": true,
"nullable": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership that is only visible to your backend.",
"additionalProperties": true,
"nullable": true
}
},
"required": [
"user_id",
"role"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMembership"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"operationId": "ListOrganizationMemberships",
"x-speakeasy-group": "organizationMemberships",
"x-speakeasy-name-override": "list",
"summary": "Get a list of all members of an organization",
"description": "Retrieves all user memberships for the given organization",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"in": "query",
"required": false,
"name": "order_by",
"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.\"",
"schema": {
"type": "string"
}
},
{
"name": "user_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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.",
"required": false
},
{
"name": "email_address",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.",
"required": false
},
{
"name": "phone_number",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.",
"required": false
},
{
"name": "username",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified usernames.\nAccepts up to 100 usernames.\nAny usernames not found are ignored.",
"required": false
},
{
"name": "web3_wallet",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified web3 wallet addresses.\nAccepts up to 100 web3 wallet addresses.\nAny web3 wallet addresses not found are ignored.",
"required": false
},
{
"name": "role",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored.",
"required": false
},
{
"name": "query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "email_address_query",
"in": "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`.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "phone_number_query",
"in": "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`.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "username_query",
"in": "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`.",
"schema": {
"type": "string"
}
},
{
"name": "name_query",
"in": "query",
"description": "Returns users with names that match the given query, via case-insensitive partial match.",
"schema": {
"type": "string"
}
},
{
"name": "last_active_at_before",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "last_active_at_after",
"in": "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.",
"example": 1700690400000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_before",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"name": "created_at_after",
"in": "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.",
"example": 1730160000000,
"schema": {
"type": "integer"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMemberships"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/memberships/{user_id}": {
"patch": {
"operationId": "UpdateOrganizationMembership",
"x-speakeasy-group": "organizationMemberships",
"x-speakeasy-name-override": "update",
"summary": "Update an organization membership",
"description": "Updates the properties of an existing organization membership",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization to which this membership belongs"
},
{
"in": "path",
"required": true,
"name": "user_id",
"schema": {
"type": "string"
},
"description": "The ID of the user to which this membership belongs"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "The new role of the given membership."
}
},
"required": [
"role"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMembership"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOrganizationMembership",
"x-speakeasy-group": "organizationMemberships",
"x-speakeasy-name-override": "delete",
"summary": "Remove a member from an organization",
"description": "Removes the given membership from the organization",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization to which this membership belongs"
},
{
"in": "path",
"required": true,
"name": "user_id",
"schema": {
"type": "string"
},
"description": "The ID of the user to which this membership belongs"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMembership"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/memberships/{user_id}/metadata": {
"patch": {
"operationId": "UpdateOrganizationMembershipMetadata",
"x-speakeasy-group": "organizationMemberships",
"x-speakeasy-name-override": "updateMetadata",
"summary": "Merge and update organization membership metadata",
"description": "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`.",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization to which this membership belongs"
},
{
"in": "path",
"required": true,
"name": "user_id",
"schema": {
"type": "string"
},
"description": "The ID of the user to which this membership belongs"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value.",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership that is only visible to your backend.\nThe new object will be merged with the existing value.",
"additionalProperties": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMembership"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/domains": {
"post": {
"operationId": "CreateOrganizationDomain",
"x-speakeasy-group": "organizationDomains",
"x-speakeasy-name-override": "create",
"summary": "Create a new organization domain.",
"description": "Creates a new organization domain. By default the domain is verified, but can be optionally set to unverified.",
"tags": [
"Organization Domains"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization where the new domain will be created."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The name of the new domain",
"nullable": false
},
"enrollment_mode": {
"type": "string",
"description": "The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation`",
"nullable": false
},
"verified": {
"type": "boolean",
"description": "The status of domain's verification. Defaults to true",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationDomain"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"get": {
"operationId": "ListOrganizationDomains",
"x-speakeasy-group": "organizationDomains",
"x-speakeasy-name-override": "list",
"summary": "Get a list of all domains of an organization.",
"description": "Get a list of all domains of an organization.",
"tags": [
"Organization Domains"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The organization ID."
},
{
"in": "query",
"required": false,
"name": "verified",
"description": "Filter domains by their verification status. `true` or `false`",
"schema": {
"type": "string"
}
},
{
"in": "query",
"required": false,
"name": "enrollment_mode",
"description": "Filter domains by their enrollment mode",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationDomains"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organizations/{organization_id}/domains/{domain_id}": {
"patch": {
"operationId": "UpdateOrganizationDomain",
"x-speakeasy-group": "organizationDomains",
"x-speakeasy-name-override": "update",
"summary": "Update an organization domain.",
"description": "Updates the properties of an existing organization domain.",
"tags": [
"Organization Domains"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization to which the domain belongs"
},
{
"in": "path",
"required": true,
"name": "domain_id",
"schema": {
"type": "string"
},
"description": "The ID of the domain"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"enrollment_mode": {
"type": "string",
"description": "The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation`",
"nullable": true
},
"verified": {
"type": "boolean",
"description": "The status of the domain's verification",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationDomain"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOrganizationDomain",
"x-speakeasy-group": "organizationDomains",
"x-speakeasy-name-override": "delete",
"summary": "Remove a domain from an organization.",
"description": "Removes the given domain from the organization.",
"tags": [
"Organization Domains"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "organization_id",
"schema": {
"type": "string"
},
"description": "The ID of the organization to which the domain belongs"
},
{
"in": "path",
"required": true,
"name": "domain_id",
"schema": {
"type": "string"
},
"description": "The ID of the domain"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/organization_domains": {
"get": {
"operationId": "ListAllOrganizationDomains",
"x-speakeasy-group": "organizationDomains",
"x-speakeasy-name-override": "listAll",
"summary": "List all organization domains",
"description": "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",
"tags": [
"Organization Domains"
],
"parameters": [
{
"in": "query",
"name": "organization_id",
"description": "The ID of the organization to filter domains by",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "verified",
"description": "Filter by verification status",
"required": false,
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"in": "query",
"name": "enrollment_mode",
"description": "Filter by enrollment mode",
"required": false,
"style": "form",
"explode": false,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"manual_invitation",
"automatic_invitation",
"automatic_suggestion"
]
}
}
},
{
"in": "query",
"name": "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",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "domains",
"description": "Filter by exact domain names. Accepts multiple values (e.g. domains=example.com&domains=test.org).",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
{
"in": "query",
"name": "order_by",
"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",
"required": false,
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"$ref": "#/components/parameters/LimitParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationDomains"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/proxy_checks": {
"post": {
"summary": "Verify the proxy configuration for your domain",
"x-speakeasy-group": "proxyChecks",
"x-speakeasy-name-override": "verify",
"description": "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 yet, or operate on\na different proxy URL than the one provided. It can also be used to re-validate a domain that is already configured to work with a proxy.",
"operationId": "VerifyDomainProxy",
"tags": [
"Proxy Checks"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"domain_id": {
"type": "string",
"description": "The ID of the domain that will be updated."
},
"proxy_url": {
"type": "string",
"description": "The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. e.g. https://example.com/__clerk"
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/ProxyCheck"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/redirect_urls": {
"get": {
"summary": "List all redirect URLs",
"x-speakeasy-group": "redirectUrls",
"x-speakeasy-name-override": "list",
"description": "Lists all whitelisted redirect_urls for the instance",
"operationId": "ListRedirectURLs",
"tags": [
"Redirect URLs"
],
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/RedirectURL.List"
}
}
},
"post": {
"summary": "Create a redirect URL",
"x-speakeasy-group": "redirectUrls",
"x-speakeasy-name-override": "create",
"description": "Create a redirect URL",
"operationId": "CreateRedirectURL",
"tags": [
"Redirect URLs"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The full URL value prefixed with `https://` or a custom scheme e.g. `\"https://my-app.com/oauth-callback\"` or `\"my-app://oauth-callback\"`"
}
},
"required": [
"url"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/RedirectURL"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/redirect_urls/{id}": {
"get": {
"summary": "Retrieve a redirect URL",
"x-speakeasy-group": "redirectUrls",
"x-speakeasy-name-override": "get",
"description": "Retrieve the details of the redirect URL with the given ID",
"operationId": "GetRedirectURL",
"tags": [
"Redirect URLs"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the redirect URL",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/RedirectURL"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"delete": {
"summary": "Delete a redirect URL",
"x-speakeasy-group": "redirectUrls",
"x-speakeasy-name-override": "delete",
"description": "Remove the selected redirect URL from the whitelist of the instance",
"operationId": "DeleteRedirectURL",
"tags": [
"Redirect URLs"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the redirect URL",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sign_in_tokens": {
"post": {
"summary": "Create sign-in token",
"x-speakeasy-group": "signInTokens",
"x-speakeasy-name-override": "create",
"description": "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.",
"operationId": "CreateSignInToken",
"tags": [
"Sign-in Tokens"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"description": "The ID of the user that can use the newly created sign in token"
},
"expires_in_seconds": {
"type": "integer",
"description": "Optional parameter to specify the life duration of the sign in token in seconds.\nBy default, the duration is 30 days.",
"minimum": 1,
"default": 2592000,
"nullable": true
}
},
"required": [
"user_id"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SignInToken"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/sign_in_tokens/{sign_in_token_id}/revoke": {
"post": {
"operationId": "RevokeSignInToken",
"x-speakeasy-group": "signInTokens",
"x-speakeasy-name-override": "revoke",
"summary": "Revoke the given sign-in token",
"description": "Revokes a pending sign-in token",
"tags": [
"Sign-in Tokens"
],
"parameters": [
{
"name": "sign_in_token_id",
"in": "path",
"description": "The ID of the sign-in token to be revoked",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/SignInToken"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/sign_ups/{id}": {
"get": {
"operationId": "GetSignUp",
"x-speakeasy-group": "signUps",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a sign-up by ID",
"description": "Retrieve the details of the sign-up with the given ID",
"tags": [
"Sign Ups"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the sign-up to retrieve",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/SignUp"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
}
}
},
"patch": {
"operationId": "UpdateSignUp",
"x-speakeasy-group": "signUps",
"x-speakeasy-name-override": "update",
"summary": "Update a sign-up",
"description": "Update the sign-up with the given ID",
"tags": [
"Sign Ups"
],
"parameters": [
{
"name": "id",
"in": "path",
"description": "The ID of the sign-up to update",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"external_id": {
"type": "string",
"description": "The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution.\nThis will be copied to the resulting user when the sign-up is completed.",
"nullable": true
},
"custom_action": {
"type": "boolean",
"description": "If true, the sign-up will be marked as a custom action.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SignUp"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
}
}
}
},
"/oauth_applications": {
"get": {
"operationId": "ListOAuthApplications",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "list",
"summary": "Get a list of OAuth applications for an instance",
"description": "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.",
"tags": [
"OAuth Applications"
],
"parameters": [
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"name": "order_by",
"in": "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.",
"required": false,
"schema": {
"type": "string",
"default": "+created_at"
}
},
{
"name": "name_query",
"in": "query",
"description": "Returns OAuth applications with names that match the given query, via case-insensitive partial match.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OAuthApplications"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateOAuthApplication",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "create",
"summary": "Create an OAuth application",
"description": "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...",
"tags": [
"OAuth Applications"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the new OAuth application.\nMax length: 256"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of redirect URIs of the new OAuth application",
"nullable": true
},
"callback_url": {
"type": "string",
"maxLength": 1024,
"description": "The callback URL of the new OAuth application",
"nullable": true,
"deprecated": true
},
"scopes": {
"type": "string",
"maxLength": 1024,
"description": "Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces.",
"default": "profile email",
"example": "profile email public_metadata",
"nullable": true
},
"consent_screen_enabled": {
"type": "boolean",
"default": true,
"description": "True to enable a consent screen to display in the authentication flow.",
"nullable": true
},
"pkce_required": {
"type": "boolean",
"default": false,
"description": "True to require the Proof Key of Code Exchange (PKCE) flow.",
"nullable": true
},
"public": {
"type": "boolean",
"description": "If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.",
"nullable": true
}
},
"required": [
"name"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OAuthApplicationWithSecret"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/oauth_applications/{oauth_application_id}": {
"get": {
"operationId": "GetOAuthApplication",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "get",
"summary": "Retrieve an OAuth application by ID",
"description": "Fetches the OAuth application whose ID matches the provided `id` in the path.",
"tags": [
"OAuth Applications"
],
"parameters": [
{
"in": "path",
"name": "oauth_application_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the OAuth application"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OAuthApplication"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateOAuthApplication",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "update",
"summary": "Update an OAuth application",
"description": "Updates an existing OAuth application",
"tags": [
"OAuth Applications"
],
"parameters": [
{
"in": "path",
"name": "oauth_application_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the OAuth application to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The new name of the OAuth application.\nMax length: 256",
"nullable": true
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of redirect URIs of the new OAuth application",
"nullable": true
},
"callback_url": {
"type": "string",
"maxLength": 1024,
"description": "The new callback URL of the OAuth application",
"nullable": true,
"deprecated": true
},
"scopes": {
"type": "string",
"maxLength": 1024,
"description": "Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces.",
"default": "profile email",
"example": "profile email public_metadata private_metadata",
"nullable": true
},
"consent_screen_enabled": {
"type": "boolean",
"description": "True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications.",
"nullable": true
},
"pkce_required": {
"type": "boolean",
"description": "True to require the Proof Key of Code Exchange (PKCE) flow.",
"nullable": true
},
"public": {
"type": "boolean",
"description": "If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/OAuthApplication"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOAuthApplication",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "delete",
"summary": "Delete an OAuth application",
"description": "Deletes the given OAuth application.\nThis is not reversible.",
"tags": [
"OAuth Applications"
],
"parameters": [
{
"in": "path",
"name": "oauth_application_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the OAuth application to delete"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/oauth_applications/{oauth_application_id}/rotate_secret": {
"post": {
"operationId": "RotateOAuthApplicationSecret",
"x-speakeasy-group": "oauthApplications",
"x-speakeasy-name-override": "rotateSecret",
"summary": "Rotate the client secret of the given OAuth application",
"description": "Rotates the OAuth application's client secret.\nWhen the client secret is rotated, make sure to update it in authorized OAuth clients.",
"tags": [
"OAuth Applications"
],
"parameters": [
{
"name": "oauth_application_id",
"in": "path",
"description": "The ID of the OAuth application for which to rotate the client secret",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OAuthApplicationWithSecret"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/saml_connections": {
"get": {
"operationId": "ListSAMLConnections",
"x-speakeasy-group": "samlConnections",
"x-speakeasy-name-override": "list",
"summary": "Get a list of SAML Connections for an instance",
"description": "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.",
"tags": [
"SAML Connections"
],
"parameters": [
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"name": "query",
"in": "query",
"required": false,
"description": "Returns SAML connections that have a name that matches the given query, via case-insensitive partial match.",
"schema": {
"type": "string"
}
},
{
"name": "order_by",
"in": "query",
"required": false,
"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.",
"schema": {
"type": "string"
}
},
{
"name": "organization_id",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"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."
}
],
"responses": {
"200": {
"$ref": "#/components/responses/SAMLConnections"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateSAMLConnection",
"x-speakeasy-group": "samlConnections",
"x-speakeasy-name-override": "create",
"summary": "Create a SAML Connection",
"description": "Create a new SAML Connection.",
"tags": [
"SAML Connections"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The name to use as a label for this SAML Connection"
},
"domain": {
"type": "string",
"deprecated": true,
"description": "The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection."
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection."
},
"provider": {
"type": "string",
"description": "The IdP provider of the connection.",
"enum": [
"saml_custom",
"saml_okta",
"saml_google",
"saml_microsoft"
]
},
"idp_entity_id": {
"type": "string",
"description": "The Entity ID as provided by the IdP",
"nullable": true
},
"idp_sso_url": {
"type": "string",
"description": "The Single-Sign On URL as provided by the IdP",
"nullable": true
},
"idp_certificate": {
"type": "string",
"description": "The X.509 certificate as provided by the IdP",
"nullable": true
},
"idp_metadata_url": {
"type": "string",
"description": "The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties",
"nullable": true
},
"idp_metadata": {
"type": "string",
"description": "The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties",
"nullable": true
},
"organization_id": {
"type": "string",
"description": "The ID of the organization to which users of this SAML Connection will be added",
"nullable": true
},
"attribute_mapping": {
"type": "object",
"description": "Define the attribute name mapping between Identity Provider and Clerk's user properties",
"nullable": true,
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string"
},
"email_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
}
}
},
"force_authn": {
"type": "boolean",
"description": "Enable or deactivate ForceAuthn"
}
},
"required": [
"name",
"provider"
],
"anyOf": [
{
"required": [
"domain"
]
},
{
"required": [
"domains"
]
}
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SAMLConnection"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/saml_connections/{saml_connection_id}": {
"get": {
"operationId": "GetSAMLConnection",
"x-speakeasy-group": "samlConnections",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a SAML Connection by ID",
"description": "Fetches the SAML Connection whose ID matches the provided `saml_connection_id` in the path.",
"tags": [
"SAML Connections"
],
"parameters": [
{
"in": "path",
"name": "saml_connection_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the SAML Connection"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/SAMLConnection"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateSAMLConnection",
"x-speakeasy-group": "samlConnections",
"x-speakeasy-name-override": "update",
"summary": "Update a SAML Connection",
"description": "Updates the SAML Connection whose ID matches the provided `id` in the path.",
"tags": [
"SAML Connections"
],
"parameters": [
{
"in": "path",
"name": "saml_connection_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the SAML Connection to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"description": "The name of the new SAML Connection",
"nullable": true
},
"domain": {
"type": "string",
"description": "The domain to use for the new SAML Connection",
"deprecated": true,
"nullable": true
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true,
"description": "A list of the domains on use for the SAML connection"
},
"idp_entity_id": {
"type": "string",
"description": "The Entity ID as provided by the IdP",
"nullable": true
},
"idp_sso_url": {
"type": "string",
"description": "The SSO URL as provided by the IdP",
"nullable": true
},
"idp_certificate": {
"type": "string",
"description": "The x509 certificated as provided by the IdP",
"nullable": true
},
"idp_metadata_url": {
"type": "string",
"description": "The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them",
"nullable": true
},
"idp_metadata": {
"type": "string",
"description": "The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties",
"nullable": true
},
"organization_id": {
"type": "string",
"description": "The ID of the organization to which users of this SAML Connection will be added",
"nullable": true
},
"attribute_mapping": {
"type": "object",
"description": "Define the attribute name mapping between Identity Provider and Clerk's user properties",
"nullable": true,
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string"
},
"email_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
}
}
},
"active": {
"type": "boolean",
"description": "Activate or de-activate the SAML Connection",
"nullable": true
},
"sync_user_attributes": {
"type": "boolean",
"description": "Controls whether to update the user's attributes in each sign-in",
"nullable": true
},
"allow_subdomains": {
"type": "boolean",
"description": "Allow users with an email address subdomain to use this connection in order to authenticate",
"nullable": true
},
"allow_idp_initiated": {
"type": "boolean",
"description": "Enable or deactivate IdP-initiated flows",
"nullable": true
},
"disable_additional_identifications": {
"type": "boolean",
"description": "Enable or deactivate additional identifications",
"nullable": true
},
"force_authn": {
"type": "boolean",
"description": "Enable or deactivate ForceAuthn"
},
"consent_verified_domains_deletion": {
"type": "boolean",
"description": "When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/SAMLConnection"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteSAMLConnection",
"x-speakeasy-group": "samlConnections",
"x-speakeasy-name-override": "delete",
"summary": "Delete a SAML Connection",
"description": "Deletes the SAML Connection whose ID matches the provided `id` in the path.",
"tags": [
"SAML Connections"
],
"parameters": [
{
"in": "path",
"name": "saml_connection_id",
"required": true,
"schema": {
"type": "string"
},
"description": "The ID of the SAML Connection to delete"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/testing_tokens": {
"post": {
"operationId": "CreateTestingToken",
"x-speakeasy-group": "testingTokens",
"x-speakeasy-name-override": "create",
"summary": "Retrieve a new testing token",
"description": "Retrieve a new testing token.",
"tags": [
"Testing Tokens"
],
"responses": {
"200": {
"$ref": "#/components/responses/TestingToken"
}
}
}
},
"/organization_memberships": {
"get": {
"operationId": "InstanceGetOrganizationMemberships",
"x-speakeasy-group": "users",
"x-speakeasy-name-override": "getInstanceOrganizationMemberships",
"summary": "Get a list of all organization memberships within an instance.",
"description": "Retrieves all organization user memberships for the given instance.",
"tags": [
"Organization Memberships"
],
"parameters": [
{
"name": "order_by",
"in": "query",
"required": false,
"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.",
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/OrganizationMemberships"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/waitlist_entries": {
"get": {
"operationId": "ListWaitlistEntries",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "list",
"summary": "List all waitlist entries",
"description": "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.",
"tags": [
"Waitlist Entries"
],
"parameters": [
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "query",
"description": "Filter waitlist entries by `email_address` or `id`",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "status",
"description": "Filter waitlist entries by their status",
"required": false,
"schema": {
"type": "string",
"enum": [
"pending",
"invited",
"completed",
"rejected"
]
}
},
{
"in": "query",
"name": "order_by",
"required": false,
"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`.",
"schema": {
"type": "string",
"default": "-created_at"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/WaitlistEntries"
}
}
},
"post": {
"operationId": "CreateWaitlistEntry",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "create",
"summary": "Create a waitlist entry",
"description": "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.",
"tags": [
"Waitlist Entries"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email_address": {
"type": "string",
"description": "The email address to add to the waitlist"
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether a confirmation email should be sent to the given email address.\nDefaults to `true`.",
"default": true,
"nullable": true
}
},
"required": [
"email_address"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/WaitlistEntry"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/waitlist_entries/bulk": {
"post": {
"operationId": "CreateBulkWaitlistEntries",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "bulkCreate",
"summary": "Create multiple waitlist entries",
"description": "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 per API call. If you need to add more entries, please make multiple requests.",
"tags": [
"Waitlist Entries"
],
"requestBody": {
"description": "Required parameters",
"content": {
"application/json": {
"schema": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"email_address": {
"type": "string",
"format": "email",
"description": "The email address to add to the waitlist"
},
"notify": {
"type": "boolean",
"description": "Optional flag which denotes whether a confirmation email should be sent to the given email address.\nDefaults to `true`.",
"nullable": true,
"default": true
}
},
"required": [
"email_address"
]
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/WaitlistEntry.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/waitlist_entries/{waitlist_entry_id}": {
"delete": {
"operationId": "DeleteWaitlistEntry",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "delete",
"summary": "Delete a pending waitlist entry",
"description": "Delete a pending waitlist entry.",
"tags": [
"Waitlist Entries"
],
"parameters": [
{
"name": "waitlist_entry_id",
"in": "path",
"description": "The ID of the waitlist entry to delete",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/waitlist_entries/{waitlist_entry_id}/invite": {
"post": {
"operationId": "InviteWaitlistEntry",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "invite",
"summary": "Invite a waitlist entry",
"description": "Send an invite to the email address in a waitlist entry.",
"tags": [
"Waitlist Entries"
],
"parameters": [
{
"name": "waitlist_entry_id",
"in": "path",
"description": "The ID of the waitlist entry to invite",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ignore_existing": {
"type": "boolean",
"description": "Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.",
"nullable": true,
"default": false
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/WaitlistEntry"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/waitlist_entries/{waitlist_entry_id}/reject": {
"post": {
"operationId": "RejectWaitlistEntry",
"x-speakeasy-group": "waitlistEntries",
"x-speakeasy-name-override": "reject",
"summary": "Reject a waitlist entry",
"description": "Reject a waitlist entry.",
"tags": [
"Waitlist Entries"
],
"parameters": [
{
"name": "waitlist_entry_id",
"in": "path",
"description": "The ID of the waitlist entry to reject",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/WaitlistEntry"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/accountless_applications": {
},
"/accountless_applications/complete": {
},
"/platform/users": {
},
"/platform/organizations": {
},
"/platform/applications": {
},
"/platform/organizations/{organizationID}": {
},
"/platform/applications/{applicationID}": {
},
"/platform/applications/{applicationID}/transfer_ownership": {
},
"/platform/applications/{applicationID}/usage": {
},
"/platform/applications/{applicationID}/subscription": {
},
"/platform/applications/{applicationID}/rotate_secret_keys": {
},
"/platform/applications/{applicationID}/logo": {
},
"/platform/applications/{applicationID}/favicon": {
},
"/platform/applications/{applicationID}/domain": {
},
"/platform/applications/{applicationID}/domains": {
},
"/platform/applications/{applicationID}/domains/{domainIDOrName}": {
},
"/platform/applications/{applicationID}/domains/{domainIDOrName}/status": {
},
"/platform/applications/{applicationID}/domains/{domainIDOrName}/dns_check": {
},
"/platform/applications/{applicationID}/transfers": {
},
"/platform/applications/{applicationID}/transfers/{transferID}": {
},
"/platform/application_transfers": {
},
"/platform/applications/{applicationID}/instances/{envOrInsID}/users": {
},
"/platform/applications/{applicationID}/instances/{envOrInsID}/users/{userID}/ban": {
},
"/platform/applications/{applicationID}/instances/{envOrInsID}/users/{userID}/unban": {
},
"/platform/applications/{applicationID}/instances/{instanceID}/config": {
},
"/platform/applications/{applicationID}/instances/{instanceID}/config/schema": {
},
"/platform/applications/{applicationID}/instances/{envOrInsID}/jwt_templates": {
},
"/platform/applications/{applicationID}/instances/{envOrInsID}/jwt_templates/{templateID}": {
},
"/billing/plans": {
"get": {
"operationId": "GetCommercePlanList",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "listPlans",
"tags": [
"Billing"
],
"summary": "List all billing plans",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "payer_type",
"description": "Filter plans by payer type",
"required": false,
"schema": {
"type": "string",
"enum": [
"user",
"org"
]
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/CommercePlan.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/prices": {
"get": {
"operationId": "GetBillingPriceList",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "listPrices",
"tags": [
"Billing"
],
"summary": "List all billing prices",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "plan_id",
"description": "Filter prices by plan ID",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/BillingPrice.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
},
"post": {
"operationId": "CreateBillingPrice",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "createPrice",
"tags": [
"Billing"
],
"summary": "Create a custom billing price",
"description": "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.",
"requestBody": {
"description": "Parameters for creating a custom price",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBillingPriceRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/BillingPrice"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/subscription_items": {
"get": {
"operationId": "GetCommerceSubscriptionItemList",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "listSubscriptionItems",
"tags": [
"Billing"
],
"summary": "List all subscription items",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
},
{
"in": "query",
"name": "status",
"description": "Filter subscription items by status",
"required": false,
"schema": {
"type": "string",
"enum": [
"active",
"ended",
"past_due",
"upcoming",
"free_trial"
]
}
},
{
"in": "query",
"name": "payer_type",
"description": "Filter subscription items by payer type",
"required": false,
"schema": {
"type": "string",
"enum": [
"user",
"org"
]
}
},
{
"in": "query",
"name": "plan_id",
"description": "Filter subscription items by plan ID",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "include_free",
"description": "Whether to include free plan subscription items",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
},
{
"in": "query",
"name": "query",
"description": "Search query to filter subscription items",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/CommerceSubscriptionItem.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/subscription_items/{subscription_item_id}": {
"delete": {
"operationId": "CancelCommerceSubscriptionItem",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "cancelSubscriptionItem",
"tags": [
"Billing"
],
"summary": "Cancel a subscription item",
"description": "Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period.",
"parameters": [
{
"name": "subscription_item_id",
"in": "path",
"description": "The ID of the subscription item to cancel",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "end_now",
"description": "Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/CommerceSubscriptionItem"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/subscription_items/{subscription_item_id}/extend_free_trial": {
"post": {
"operationId": "ExtendBillingSubscriptionItemFreeTrial",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "extendSubscriptionItemFreeTrial",
"tags": [
"Billing"
],
"summary": "Extend free trial for a subscription item",
"description": "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.",
"parameters": [
{
"name": "subscription_item_id",
"in": "path",
"description": "The ID of the subscription item to extend the free trial for",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Parameters for extending the free trial",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExtendFreeTrialRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/responses-CommerceSubscriptionItem"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/subscription_items/{subscription_item_id}/price_transition": {
"post": {
"operationId": "CreateBillingPriceTransition",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "createPriceTransition",
"tags": [
"Billing"
],
"summary": "Create a price transition for a subscription item",
"description": "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.",
"parameters": [
{
"name": "subscription_item_id",
"in": "path",
"description": "The ID of the subscription item to transition",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Parameters for the price transition",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PriceTransitionRequest"
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/CommercePriceTransition"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"409": {
"$ref": "#/components/responses/Conflict"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/statements": {
"get": {
"operationId": "GetBillingStatementList",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "listStatements",
"tags": [
"Billing"
],
"summary": "List all billing statements",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/BillingStatement.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/statements/{statementID}": {
"get": {
"operationId": "GetBillingStatement",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "getStatement",
"tags": [
"Billing"
],
"summary": "Retrieve a billing statement",
"description": "Retrieves the details of a billing statement.",
"parameters": [
{
"name": "statementID",
"in": "path",
"description": "The ID of the statement to retrieve.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"$ref": "#/components/responses/BillingStatement"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/billing/statements/{statementID}/payment_attempts": {
"get": {
"operationId": "GetBillingStatementPaymentAttempts",
"x-speakeasy-group": "billing",
"x-speakeasy-name-override": "getStatementPaymentAttempts",
"tags": [
"Billing"
],
"summary": "List payment attempts for a billing statement",
"description": "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.",
"parameters": [
{
"name": "statementID",
"in": "path",
"description": "The ID of the statement to retrieve payment attempts for.",
"required": true,
"schema": {
"type": "string"
}
},
{
"$ref": "#/components/parameters/Paginated"
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/BillingPaymentAttempt.List"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
},
"500": {
"$ref": "#/components/responses/ClerkErrors"
}
}
}
},
"/organization_permissions": {
"get": {
"operationId": "ListOrganizationPermissions",
"x-speakeasy-group": "organizationPermissions",
"x-speakeasy-name-override": "list",
"summary": "Get a list of all organization permissions",
"description": "Retrieves all organization permissions for the given instance.",
"tags": [
"Organization Permissions"
],
"parameters": [
{
"name": "query",
"in": "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.",
"schema": {
"type": "string"
},
"required": false
},
{
"name": "order_by",
"in": "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`.",
"schema": {
"type": "string"
},
"required": false
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Permissions"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateOrganizationPermission",
"x-speakeasy-group": "organizationPermissions",
"x-speakeasy-name-override": "create",
"summary": "Create a new organization permission",
"description": "Creates a new organization permission for the given instance.",
"tags": [
"Organization Permissions"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the permission."
},
"key": {
"type": "string",
"description": "The key of the permission. Must have the format \"org:feature:action\" where feature and action are segments consisting of lowercase letters, digits, or underscores, for example \"org:billing:manage\" or \"org:team:read\". Cannot begin with \"org:sys_\" as that prefix is reserved for system permissions."
},
"description": {
"type": "string",
"description": "A description of the permission."
}
},
"required": [
"name",
"key"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Permission"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/organization_permissions/{permission_id}": {
"get": {
"operationId": "GetOrganizationPermission",
"x-speakeasy-group": "organizationPermissions",
"x-speakeasy-name-override": "get",
"summary": "Get an organization permission",
"description": "Retrieves the details of an organization permission.",
"tags": [
"Organization Permissions"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "permission_id",
"schema": {
"type": "string"
},
"description": "The ID of the permission to retrieve"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/Permission"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateOrganizationPermission",
"x-speakeasy-group": "organizationPermissions",
"x-speakeasy-name-override": "update",
"summary": "Update an organization permission",
"description": "Updates the properties of an existing organization permission.\nSystem permissions cannot be updated.",
"tags": [
"Organization Permissions"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "permission_id",
"schema": {
"type": "string"
},
"description": "The ID of the permission to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the permission."
},
"key": {
"type": "string",
"description": "The key of the permission. Must have the format \"org:feature:action\" where feature and action are segments consisting of lowercase letters, digits, or underscores. Cannot begin with \"org:sys_\" as that prefix is reserved for system permissions."
},
"description": {
"type": "string",
"description": "A description of the permission."
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/Permission"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"delete": {
"operationId": "DeleteOrganizationPermission",
"x-speakeasy-group": "organizationPermissions",
"x-speakeasy-name-override": "delete",
"summary": "Delete an organization permission",
"description": "Deletes an organization permission.\nSystem permissions cannot be deleted.",
"tags": [
"Organization Permissions"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "permission_id",
"schema": {
"type": "string"
},
"description": "The ID of the permission to delete"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
}
},
"/role_sets": {
"get": {
"operationId": "ListRoleSets",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "list",
"summary": "Get a list of role sets",
"description": "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.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "query",
"name": "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.",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "order_by",
"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`.",
"required": false,
"schema": {
"type": "string",
"default": "-created_at"
}
},
{
"$ref": "#/components/parameters/LimitParameter"
},
{
"$ref": "#/components/parameters/OffsetParameter"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/RoleSets"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
},
"post": {
"operationId": "CreateRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "create",
"summary": "Create a role set",
"description": "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.",
"tags": [
"Role Sets"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the new role set"
},
"key": {
"type": "string",
"description": "A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.\nIf not provided, a key will be generated from the name."
},
"description": {
"type": "string",
"description": "Optional description for the role set",
"nullable": true
},
"default_role_key": {
"type": "string",
"description": "The key of the role to use as the default role for new organization members.\nMust be one of the roles in the `roles` array."
},
"creator_role_key": {
"type": "string",
"description": "The key of the role to assign to organization creators.\nMust be one of the roles in the `roles` array."
},
"type": {
"type": "string",
"enum": [
"initial",
"custom"
],
"description": "The type of the role set. \"initial\" role sets are the default for new organizations.\nOnly one role set can be \"initial\" per instance."
},
"roles": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of role keys to include in the role set.\nMust contain at least one role and no more than 10 roles."
}
},
"additionalProperties": false,
"required": [
"name",
"default_role_key",
"creator_role_key",
"roles"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/RoleSet"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/role_sets/{role_set_key_or_id}": {
"get": {
"operationId": "GetRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "get",
"summary": "Retrieve a role set",
"description": "Retrieves an existing role set by its key or ID.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "role_set_key_or_id",
"schema": {
"type": "string"
},
"description": "The key or ID of the role set"
}
],
"responses": {
"200": {
"$ref": "#/components/responses/RoleSet"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
}
}
},
"patch": {
"operationId": "UpdateRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "update",
"summary": "Update a role set",
"description": "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.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "role_set_key_or_id",
"schema": {
"type": "string"
},
"description": "The key or ID of the role set to update"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The new name for the role set",
"nullable": true
},
"key": {
"type": "string",
"description": "A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores.",
"nullable": true
},
"description": {
"type": "string",
"description": "Optional description for the role set",
"nullable": true
},
"type": {
"type": "string",
"enum": [
"initial"
],
"description": "Set to \"initial\" to make this the default role set for new organizations.\nOnly one role set can be \"initial\" per instance; setting this will change any existing initial role set to \"custom\".",
"nullable": true
},
"default_role_key": {
"type": "string",
"description": "The key of the role to use as the default role for new organization members.\nMust be an existing role in the role set.",
"nullable": true
},
"creator_role_key": {
"type": "string",
"description": "The key of the role to assign to organization creators.\nMust be an existing role in the role set.",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/RoleSet"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/role_sets/{role_set_key_or_id}/replace": {
"post": {
"operationId": "ReplaceRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "replace",
"summary": "Replace a role set",
"description": "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.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "role_set_key_or_id",
"schema": {
"type": "string"
},
"description": "The key or ID of the role set to replace"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"dest_role_set_key": {
"type": "string",
"description": "The key of the destination role set"
},
"reassignment_mappings": {
"allOf": [
{
"$ref": "#/components/schemas/ReassignmentMappings"
}
],
"description": "Mappings from source role keys to destination role keys.\nRequired if members have roles that need to be reassigned."
}
},
"required": [
"dest_role_set_key"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/DeletedObject"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/role_sets/{role_set_key_or_id}/roles": {
"post": {
"operationId": "AddRolesToRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "addRoles",
"summary": "Add roles to a role set",
"description": "Adds one or more roles to an existing role set.\nYou can optionally update the default role or creator role when adding new roles.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "role_set_key_or_id",
"schema": {
"type": "string"
},
"description": "The key or ID of the role set"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role_keys": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of role keys to add to the role set.\nMust contain at least one role and no more than 10 roles."
},
"default_role_key": {
"type": "string",
"description": "Optionally update the default role to one of the newly added roles."
},
"creator_role_key": {
"type": "string",
"description": "Optionally update the creator role to one of the newly added roles."
}
},
"required": [
"role_keys"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/RoleSet"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/role_sets/{role_set_key_or_id}/roles/replace": {
"post": {
"operationId": "ReplaceRoleInRoleSet",
"x-speakeasy-group": "roleSets",
"x-speakeasy-name-override": "replaceRole",
"summary": "Replace a role in a role set",
"description": "Replaces a role in a role set with another role. This atomically removes\nthe source role and reassigns any members to the destination role.",
"tags": [
"Role Sets"
],
"parameters": [
{
"in": "path",
"required": true,
"name": "role_set_key_or_id",
"schema": {
"type": "string"
},
"description": "The key or ID of the role set"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"role_key": {
"type": "string",
"description": "The key of the role to remove from the role set"
},
"to_role_key": {
"type": "string",
"description": "The key of the role to reassign members to"
}
},
"required": [
"role_key",
"to_role_key"
]
}
}
}
},
"responses": {
"200": {
"$ref": "#/components/responses/RoleSet"
},
"400": {
"$ref": "#/components/responses/ClerkErrors"
},
"401": {
"$ref": "#/components/responses/AuthenticationInvalid"
},
"403": {
"$ref": "#/components/responses/AuthorizationInvalid"
},
"404": {
"$ref": "#/components/responses/ResourceNotFound"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
},
"/audit_logs": {
},
"/api_keys": {
"post": {
"operationId": "createApiKey",
"summary": "Create an API Key",
"tags": [
"API Keys"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"type": {
"type": "string",
"minLength": 3,
"maxLength": 25,
"default": "api_key"
},
"name": {
"type": "string",
"minLength": 3,
"pattern": "^(\\S(.*\\S)?)?$"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch|scim)_\\w{27}$"
},
"claims": {
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"default": [
]
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$"
},
"seconds_until_expiration": {
"type": "number",
"nullable": true,
"minimum": 0,
"exclusiveMinimum": true
}
},
"required": [
"name",
"subject"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"secret": {
"type": "string",
"example": "ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"secret",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"409": {
"description": "409 Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
},
"get": {
"operationId": "getApiKeys",
"summary": "Get API Keys",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"minLength": 3,
"default": "api_key"
},
"required": false,
"name": "type",
"in": "query"
},
{
"schema": {
"type": "string",
"pattern": "^(user|org|mch|scim)_\\w{27}$"
},
"required": true,
"name": "subject",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"true",
"false"
],
"default": "false"
},
"required": false,
"name": "include_invalid",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0,
"default": 0
},
"required": false,
"name": "offset",
"in": "query"
},
{
"schema": {
"type": "string"
},
"required": false,
"name": "query",
"in": "query"
}
],
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total_count": {
"type": "number"
}
},
"required": [
"data",
"total_count"
]
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/api_keys/{apiKeyID}": {
"get": {
"operationId": "getApiKey",
"summary": "Get an API Key by ID",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(ak|api_key)_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "apiKeyID",
"in": "path"
}
],
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
},
"patch": {
"operationId": "updateApiKey",
"summary": "Update an API Key",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(ak|api_key)_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "apiKeyID",
"in": "path"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"claims": {
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch|scim)_\\w{27}$"
},
"seconds_until_expiration": {
"type": "number",
"nullable": true,
"minimum": 0,
"exclusiveMinimum": true
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
},
"delete": {
"operationId": "deleteApiKey",
"summary": "Delete an API Key",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(ak|api_key)_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "apiKeyID",
"in": "path"
}
],
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"deleted": {
"type": "boolean",
"enum": [
true
]
}
},
"required": [
"id",
"object",
"deleted"
]
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/api_keys/{apiKeyID}/secret": {
"get": {
"operationId": "getApiKeySecret",
"summary": "Get an API Key Secret",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(ak|api_key)_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "apiKeyID",
"in": "path"
}
],
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"secret": {
"type": "string"
}
},
"required": [
"secret"
]
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/api_keys/{apiKeyID}/revoke": {
"post": {
"operationId": "revokeApiKey",
"summary": "Revoke an API Key",
"tags": [
"API Keys"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(ak|api_key)_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "apiKeyID",
"in": "path"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"revocation_reason": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/api_keys/verify": {
"post": {
"operationId": "verifyApiKey",
"summary": "Verify an API Key",
"tags": [
"API Keys"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"secret": {
"type": "string"
}
},
"required": [
"secret"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"api_key"
]
},
"id": {
"type": "string",
"pattern": "^ak_[0-9A-Fa-f]{32}$",
"example": "ak_3beecc9c60adb5f9b850e91a8ee1e992"
},
"type": {
"type": "string",
"minLength": 3,
"example": "api_key"
},
"subject": {
"type": "string",
"pattern": "^(user|org|mch)_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"name": {
"type": "string",
"example": "MY_SERVICE_API_KEY"
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 255,
"example": "This is my API Key"
},
"claims": {
"nullable": true,
"example": {
"foo": "bar"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key will expire, in milliseconds",
"example": 1716883200
},
"created_by": {
"type": "string",
"nullable": true,
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the API key was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the API key was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the API key was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"type",
"subject",
"name",
"claims",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_by",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/m2m_tokens": {
"post": {
"x-speakeasy-group": "m2m",
"x-speakeasy-name-override": "createToken",
"operationId": "createM2MToken",
"summary": "Create a M2M Token",
"description": "Creates a new M2M Token. Must be authenticated via a Machine Secret Key.",
"tags": [
"M2M Tokens"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"seconds_until_expiration": {
"type": "number",
"nullable": true,
"minimum": 0,
"exclusiveMinimum": true
},
"claims": {
"nullable": true
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"201": {
"description": "201 Created",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"machine_to_machine_token"
]
},
"id": {
"type": "string",
"pattern": "^mt_[0-9A-Fa-f]{32}$",
"example": "mt_f7f0ba8c3b4843ce7d85fcdd5e71853e"
},
"subject": {
"type": "string",
"pattern": "^mch_\\w{27}$",
"example": "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"claims": {
"nullable": true,
"example": {
"important_metadata": "Some useful data"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^mch_\\w{27}$"
},
"default": [
],
"example": [
"mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
"mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em"
]
},
"token": {
"type": "string",
"example": "mt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token will expire, in milliseconds",
"example": 1716883200
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the token was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the token was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"subject",
"token",
"revoked",
"revocation_reason",
"expired",
"expiration",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"409": {
"description": "409 Conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
},
"get": {
"x-speakeasy-group": "m2m",
"x-speakeasy-name-override": "listTokens",
"operationId": "getM2MTokens",
"summary": "Get M2M Tokens",
"description": "Fetches M2M tokens for a specific machine.\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 retrieved.",
"tags": [
"M2M Tokens"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^mch_\\w{27}$"
},
"required": true,
"name": "subject",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true,
"default": false
},
"required": false,
"name": "revoked",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true,
"default": false
},
"required": false,
"name": "expired",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10
},
"required": false,
"name": "limit",
"in": "query"
},
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0,
"default": 0
},
"required": false,
"name": "offset",
"in": "query"
}
],
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"m2m_tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"machine_to_machine_token"
]
},
"id": {
"type": "string",
"pattern": "^mt_[0-9A-Fa-f]{32}$",
"example": "mt_f7f0ba8c3b4843ce7d85fcdd5e71853e"
},
"subject": {
"type": "string",
"pattern": "^mch_\\w{27}$",
"example": "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"claims": {
"nullable": true,
"example": {
"important_metadata": "Some useful data"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^mch_\\w{27}$"
},
"default": [
],
"example": [
"mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
"mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token will expire, in milliseconds",
"example": 1716883200
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the token was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the token was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"subject",
"revoked",
"revocation_reason",
"expired",
"expiration",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
},
"total_count": {
"type": "number"
}
},
"required": [
"m2m_tokens",
"total_count"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"403": {
"description": "403 Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/m2m_tokens/{m2m_token_id}/revoke": {
"post": {
"x-speakeasy-group": "m2m",
"x-speakeasy-name-override": "revokeToken",
"operationId": "revokeM2MToken",
"summary": "Revoke a M2M Token",
"description": "Revokes a M2M Token.\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.",
"tags": [
"M2M Tokens"
],
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^mt_[0-9A-Fa-f]{32}$"
},
"required": true,
"name": "m2m_token_id",
"in": "path"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"revocation_reason": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"machine_to_machine_token"
]
},
"id": {
"type": "string",
"pattern": "^mt_[0-9A-Fa-f]{32}$",
"example": "mt_f7f0ba8c3b4843ce7d85fcdd5e71853e"
},
"subject": {
"type": "string",
"pattern": "^mch_\\w{27}$",
"example": "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"claims": {
"nullable": true,
"example": {
"important_metadata": "Some useful data"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^mch_\\w{27}$"
},
"default": [
],
"example": [
"mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
"mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token will expire, in milliseconds",
"example": 1716883200
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the token was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the token was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"subject",
"revoked",
"revocation_reason",
"expired",
"expiration",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/m2m_tokens/verify": {
"post": {
"x-speakeasy-group": "m2m",
"x-speakeasy-name-override": "verifyToken",
"operationId": "verifyM2MToken",
"summary": "Verify a M2M Token",
"description": "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.",
"tags": [
"M2M Tokens"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"token": {
"type": "string"
}
},
"required": [
"token"
],
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"machine_to_machine_token"
]
},
"id": {
"type": "string",
"pattern": "^mt_[0-9A-Fa-f]{32}$",
"example": "mt_f7f0ba8c3b4843ce7d85fcdd5e71853e"
},
"subject": {
"type": "string",
"pattern": "^mch_\\w{27}$",
"example": "mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"claims": {
"nullable": true,
"example": {
"important_metadata": "Some useful data"
}
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^mch_\\w{27}$"
},
"default": [
],
"example": [
"mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk",
"mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token will expire, in milliseconds",
"example": 1716883200
},
"last_used_at": {
"type": "number",
"nullable": true,
"description": "The timestamp for when the token was last used, in milliseconds",
"example": 1716883200
},
"created_at": {
"type": "number",
"description": "The timestamp for when the token was created, in milliseconds",
"example": 1716883200
},
"updated_at": {
"type": "number",
"description": "The timestamp for when the token was last updated, in milliseconds",
"example": 1716883200
}
},
"required": [
"object",
"id",
"subject",
"revoked",
"revocation_reason",
"expired",
"expiration",
"last_used_at",
"created_at",
"updated_at"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
},
"/oauth_applications/access_tokens/verify": {
"post": {
"x-speakeasy-group": "oauthAccessTokens",
"x-speakeasy-name-override": "verify",
"operationId": "verifyOAuthAccessToken",
"summary": "Verify an OAuth Access Token",
"tags": [
"OAuth Access Tokens"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"access_token": {
"type": "string",
"description": "The access token to verify.",
"example": "XXXXXXXXXXXXXX"
},
"secret": {
"type": "string",
"description": "The access token to verify. This is deprecated, use `access_token` instead.",
"deprecated": true,
"example": "XXXXXXXXXXXXXX"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200 OK",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"clerk_idp_oauth_access_token"
],
"example": "clerk_idp_oauth_access_token"
},
"id": {
"type": "string",
"pattern": "^oat_[0-9A-Fa-f]{32}$",
"example": "oat_0ef5a7a33d87ed87ee7954c845d80450"
},
"client_id": {
"type": "string",
"example": "client_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"subject": {
"type": "string",
"pattern": "^user_\\w{27}$",
"example": "user_2xhFjEI5X2qWRvtV13BzSj8H6Dk"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"read",
"write"
]
},
"revoked": {
"type": "boolean",
"example": false
},
"revocation_reason": {
"type": "string",
"nullable": true,
"example": "Revoked by user"
},
"expired": {
"type": "boolean",
"example": false
},
"expiration": {
"type": "number",
"nullable": true,
"example": 1716883200
},
"created_at": {
"type": "number",
"example": 1716883200
},
"updated_at": {
"type": "number",
"example": 1716883200
}
},
"required": [
"object",
"id",
"client_id",
"subject",
"scopes",
"revoked",
"revocation_reason",
"expired",
"expiration",
"created_at",
"updated_at"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"active": {
"type": "boolean",
"enum": [
false
],
"description": "Indicates that a JWT access token is not active (expired)",
"example": false
}
},
"required": [
"active"
],
"additionalProperties": false
}
]
}
}
}
},
"400": {
"description": "400 Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "Bad Request"
},
"long_message": {
"type": "string",
"example": "Invalid 'url_parameter.example': Failed regex check"
},
"code": {
"type": "string",
"example": "bad_request"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
},
"404": {
"description": "404 Not Found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"message": {
"type": "string",
"example": "some details about the error"
},
"long_message": {
"type": "string",
"example": "some details about the error"
},
"code": {
"type": "string",
"example": "some_error_code"
}
},
"required": [
"message",
"long_message",
"code"
]
}
}
},
"required": [
"errors"
]
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Secret key, obtained under \"API Keys\" in the Clerk Dashboard.",
"bearerFormat": "sk_<environment>_<secret value>"
},
"platformToken": {
"type": "http",
"scheme": "bearer",
"description": "Internal auth."
}
},
"schemas": {
"JWKS.ed25519.PublicKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"OKP"
]
},
"crv": {
"type": "string",
"enum": [
"Ed25519"
]
},
"x": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"crv",
"x"
]
},
"JWKS.ecdsa.PublicKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"EC"
]
},
"crv": {
"type": "string"
},
"x": {
"type": "string"
},
"y": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"crv",
"x",
"y"
]
},
"JWKS.rsa.PublicKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"RSA"
]
},
"n": {
"type": "string"
},
"e": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"n",
"e"
]
},
"JWKS.ed25519.PrivateKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"OKP"
]
},
"crv": {
"type": "string",
"enum": [
"Ed25519"
]
},
"x": {
"type": "string"
},
"d": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"crv",
"x",
"d"
]
},
"JWKS.ecdsa.PrivateKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"EC"
]
},
"crv": {
"type": "string"
},
"x": {
"type": "string"
},
"y": {
"type": "string"
},
"d": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"crv",
"x",
"y",
"d"
]
},
"JWKS.rsa.PrivateKey": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"RSA"
]
},
"n": {
"type": "string"
},
"e": {
"type": "string"
},
"d": {
"type": "string"
},
"p": {
"type": "string"
},
"q": {
"type": "string"
},
"dp": {
"type": "string"
},
"dq": {
"type": "string"
},
"qi": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"crv",
"n",
"e",
"d",
"p",
"q"
]
},
"JWKS.symmetric.Key": {
"type": "object",
"properties": {
"kid": {
"type": "string"
},
"alg": {
"type": "string"
},
"use": {
"type": "string"
},
"kty": {
"type": "string",
"enum": [
"oct"
]
},
"k": {
"type": "string"
},
"x5c": {
"type": "array",
"items": {
"type": "string"
}
},
"x5t": {
"type": "string"
},
"x5t#S256": {
"type": "string"
},
"x5u": {
"type": "string"
}
},
"required": [
"kid",
"alg",
"use",
"kty",
"k"
]
},
"JWKS": {
"type": "object",
"additionalProperties": false,
"properties": {
"keys": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/JWKS.ed25519.PublicKey"
},
{
"$ref": "#/components/schemas/JWKS.ecdsa.PublicKey"
},
{
"$ref": "#/components/schemas/JWKS.rsa.PublicKey"
},
{
"$ref": "#/components/schemas/JWKS.ed25519.PrivateKey"
},
{
"$ref": "#/components/schemas/JWKS.ecdsa.PrivateKey"
},
{
"$ref": "#/components/schemas/JWKS.rsa.PrivateKey"
},
{
"$ref": "#/components/schemas/JWKS.symmetric.Key"
}
]
}
}
}
},
"SessionActivityResponse": {
"type": "object",
"nullable": true,
"properties": {
"object": {
"type": "string"
},
"id": {
"type": "string"
},
"device_type": {
"type": "string"
},
"is_mobile": {
"type": "boolean"
},
"browser_name": {
"type": "string"
},
"browser_version": {
"type": "string"
},
"ip_address": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
}
},
"required": [
"id",
"object",
"is_mobile"
]
},
"SessionTask": {
"type": "object",
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
]
},
"Session": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"session"
]
},
"id": {
"type": "string"
},
"user_id": {
"type": "string"
},
"client_id": {
"type": "string"
},
"actor": {
"type": "object",
"nullable": true
},
"status": {
"type": "string",
"enum": [
"active",
"revoked",
"ended",
"expired",
"removed",
"abandoned",
"replaced",
"pending"
]
},
"last_active_organization_id": {
"type": "string",
"nullable": true
},
"last_active_at": {
"type": "integer"
},
"latest_activity": {
"$ref": "#/components/schemas/SessionActivityResponse"
},
"expire_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of expiration.\n"
},
"abandon_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of abandonment.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"tasks": {
"type": "array",
"nullable": true,
"items": {
"$ref": "#/components/schemas/SessionTask"
}
}
},
"required": [
"object",
"id",
"user_id",
"client_id",
"status",
"last_active_at",
"expire_at",
"abandon_at",
"updated_at",
"created_at"
]
},
"Client": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"client"
]
},
"id": {
"type": "string",
"description": "String representing the identifier of the session.\n"
},
"session_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"sessions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
},
"sign_in_id": {
"type": "string",
"nullable": true
},
"sign_up_id": {
"type": "string",
"nullable": true
},
"last_active_session_id": {
"nullable": true,
"type": "string",
"description": "Last active session_id.\n"
},
"last_authentication_strategy": {
"nullable": true,
"type": "string",
"description": "The authentication strategy that was last used to authenticate the user on this client.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
}
},
"required": [
"object",
"id",
"session_ids",
"sessions",
"sign_in_id",
"sign_up_id",
"last_active_session_id",
"last_authentication_strategy",
"updated_at",
"created_at"
]
},
"ClerkError": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"long_message": {
"type": "string"
},
"code": {
"type": "string"
},
"meta": {
"type": "object"
}
},
"required": [
"message",
"long_message",
"code"
]
},
"ClerkErrors": {
"type": "object",
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClerkError"
}
},
"meta": {
"type": "object"
},
"clerk_trace_id": {
"type": "string"
}
},
"required": [
"errors"
]
},
"verification_otp": {
"x-speakeasy-name-override": "OTP",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_otp"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified",
"failed",
"expired"
]
},
"strategy": {
"x-speakeasy-unknown-values": "allow",
"type": "string",
"enum": [
"phone_code",
"email_code",
"reset_password_email_code"
]
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"verification_admin": {
"x-speakeasy-name-override": "Admin",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_admin"
]
},
"status": {
"type": "string",
"enum": [
"verified"
]
},
"strategy": {
"x-speakeasy-unknown-values": "allow",
"type": "string",
"enum": [
"admin"
]
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"verification_from_oauth": {
"x-speakeasy-name-override": "FromOAuth",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_from_oauth"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified"
]
},
"strategy": {
"type": "string",
"pattern": "^from_oauth_(?:(?:token_)|(?:custom_))?[a-z]+$"
},
"error": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
]
},
"expire_at": {
"type": "integer",
"nullable": true
},
"attempts": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"verification_ticket": {
"x-speakeasy-name-override": "Ticket",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_ticket"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified",
"expired"
]
},
"strategy": {
"x-speakeasy-unknown-values": "allow",
"type": "string",
"enum": [
"ticket"
]
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"verification_saml": {
"x-speakeasy-name-override": "SAML",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_saml"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified",
"failed",
"expired",
"transferable"
]
},
"strategy": {
"type": "string",
"enum": [
"saml"
]
},
"external_verification_redirect_url": {
"nullable": true,
"type": "string"
},
"error": {
"nullable": true,
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
]
},
"expire_at": {
"type": "integer",
"nullable": true
},
"attempts": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts"
]
},
"verification_email_link": {
"x-speakeasy-name-override": "EmailLink",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_email_link"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified",
"failed",
"expired"
]
},
"strategy": {
"type": "string",
"enum": [
"email_link"
]
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"IdentificationLink": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"pattern": "^oauth_[a-z]+$"
},
"id": {
"type": "string"
}
},
"required": [
"type",
"id"
]
},
"EmailAddress": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"x-speakeasy-unknown-values": "allow",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"email_address"
]
},
"email_address": {
"type": "string"
},
"reserved": {
"type": "boolean"
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_otp"
},
{
"$ref": "#/components/schemas/verification_admin"
},
{
"$ref": "#/components/schemas/verification_from_oauth"
},
{
"$ref": "#/components/schemas/verification_ticket"
},
{
"$ref": "#/components/schemas/verification_saml"
},
{
"$ref": "#/components/schemas/verification_email_link"
}
],
"discriminator": {
"propertyName": "object",
"mapping": {
"verification_otp": "#/components/schemas/verification_otp",
"verification_admin": "#/components/schemas/verification_admin",
"verification_from_oauth": "#/components/schemas/verification_from_oauth",
"verification_ticket": "#/components/schemas/verification_ticket",
"verification_saml": "#/components/schemas/verification_saml",
"verification_email_link": "#/components/schemas/verification_email_link"
}
}
},
"linked_to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IdentificationLink"
}
},
"matches_sso_connection": {
"description": "Indicates whether this email address domain matches an active enterprise connection.\n",
"type": "boolean"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
}
},
"required": [
"object",
"email_address",
"verification",
"linked_to",
"reserved",
"created_at",
"updated_at"
]
},
"DeletedObject": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string"
},
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"deleted": {
"type": "boolean"
},
"external_id": {
"type": "string"
}
},
"required": [
"object",
"deleted"
]
},
"PhoneNumber": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"phone_number"
]
},
"phone_number": {
"type": "string"
},
"reserved_for_second_factor": {
"type": "boolean"
},
"default_second_factor": {
"type": "boolean"
},
"reserved": {
"type": "boolean"
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_otp"
},
{
"$ref": "#/components/schemas/verification_admin"
}
],
"discriminator": {
"propertyName": "object",
"mapping": {
"verification_otp": "#/components/schemas/verification_otp",
"verification_admin": "#/components/schemas/verification_admin"
}
}
},
"linked_to": {
"type": "array",
"items": {
"$ref": "#/components/schemas/IdentificationLink"
}
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
}
},
"required": [
"object",
"phone_number",
"verification",
"linked_to",
"reserved",
"created_at",
"updated_at"
]
},
"Token": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"token"
]
},
"jwt": {
"type": "string",
"description": "String representing the encoded JSON Web Token (JWT) value.\n"
}
},
"required": [
"object",
"jwt"
]
},
"Cookies": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"cookies"
]
},
"cookies": {
"type": "array",
"description": "Array of cookie directives.",
"items": {
"type": "string"
}
}
},
"required": [
"object",
"cookies"
]
},
"SessionRefresh": {
"oneOf": [
{
"$ref": "#/components/schemas/Token"
},
{
"$ref": "#/components/schemas/Cookies"
}
]
},
"Template": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"template"
]
},
"instance_id": {
"nullable": true,
"type": "string",
"description": "The ID of the instance to which the template belongs"
},
"resource_type": {
"type": "string",
"description": "whether this is a system (default) or user overridden) template"
},
"template_type": {
"type": "string",
"description": "whether this is an email or SMS template"
},
"name": {
"type": "string",
"description": "user-friendly name of the template"
},
"slug": {
"type": "string",
"description": "machine-friendly name of the template"
},
"position": {
"type": "integer",
"description": "position with the listing of templates"
},
"can_revert": {
"type": "boolean",
"description": "whether this template can be reverted to the corresponding system default"
},
"can_delete": {
"type": "boolean",
"description": "whether this template can be deleted"
},
"can_edit_body": {
"type": "boolean",
"description": "whether the body of this template can be edited"
},
"can_toggle": {
"type": "boolean",
"description": "whether this template can be enabled or disabled, true only for notification SMS templates"
},
"subject": {
"type": "string",
"description": "email subject",
"nullable": true
},
"markup": {
"type": "string",
"description": "the editor markup used to generate the body of the template"
},
"body": {
"type": "string",
"description": "the template body before variable interpolation"
},
"available_variables": {
"type": "array",
"description": "list of variables that are available for use in the template body",
"items": {
"type": "string"
}
},
"required_variables": {
"type": "array",
"description": "list of variables that must be contained in the template body",
"items": {
"type": "string"
}
},
"from_email_name": {
"type": "string"
},
"reply_to_email_name": {
"type": "string"
},
"delivered_by_clerk": {
"type": "boolean"
},
"enabled": {
"type": "boolean"
},
"flagged_as_suspicious": {
"type": "boolean"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
}
}
},
"verification_web3": {
"x-speakeasy-name-override": "Web3Signature",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_web3"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified",
"failed",
"expired"
]
},
"strategy": {
"type": "string",
"enum": [
"web3_metamask_signature",
"web3_base_signature",
"web3_coinbase_wallet_signature",
"web3_okx_wallet_signature",
"web3_solana_signature"
]
},
"nonce": {
"type": "string",
"nullable": true
},
"message": {
"type": "string",
"nullable": true
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"Web3Wallet": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"web3_wallet"
]
},
"web3_wallet": {
"type": "string"
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_web3"
},
{
"$ref": "#/components/schemas/verification_admin"
}
],
"discriminator": {
"propertyName": "object"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
}
},
"required": [
"object",
"web3_wallet",
"verification",
"created_at",
"updated_at"
]
},
"verification_passkey": {
"x-speakeasy-name-override": "Passkey",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_passkey"
]
},
"status": {
"type": "string",
"enum": [
"verified"
]
},
"strategy": {
"type": "string",
"enum": [
"passkey"
]
},
"nonce": {
"type": "string",
"enum": [
"nonce"
]
},
"message": {
"type": "string",
"nullable": true
},
"attempts": {
"type": "integer",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"Passkey": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"passkey"
]
},
"name": {
"type": "string"
},
"last_used_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the passkey was last used.\n"
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_passkey"
}
],
"discriminator": {
"propertyName": "object"
}
}
},
"required": [
"object",
"name",
"last_used_at",
"verification"
]
},
"verification_oauth": {
"x-speakeasy-name-override": "Oauth",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_oauth"
]
},
"status": {
"type": "string",
"x-speakeasy-unknown-values": "allow",
"enum": [
"unverified",
"verified",
"failed",
"expired",
"transferable"
]
},
"strategy": {
"type": "string",
"x-speakeasy-unknown-values": "allow",
"pattern": "^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$"
},
"external_verification_redirect_url": {
"type": "string"
},
"error": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
]
},
"expire_at": {
"type": "integer"
},
"attempts": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"verification_google_one_tap": {
"x-speakeasy-name-override": "GoogleOneTap",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"verification_google_one_tap"
]
},
"status": {
"type": "string",
"enum": [
"unverified",
"verified"
]
},
"strategy": {
"type": "string",
"enum": [
"google_one_tap"
]
},
"expire_at": {
"type": "integer",
"nullable": true
},
"attempts": {
"type": "integer",
"nullable": true
},
"verified_at_client": {
"type": "string",
"nullable": true
},
"error": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
]
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"ExternalAccountWithVerification": {
"type": "object",
"additionalProperties": true,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"external_account",
"facebook_account",
"google_account"
]
},
"id": {
"type": "string"
},
"provider": {
"type": "string"
},
"identification_id": {
"type": "string"
},
"provider_user_id": {
"description": "The unique ID of the user in the external provider's system",
"type": "string"
},
"approved_scopes": {
"type": "string"
},
"email_address": {
"type": "string"
},
"email_address_verified": {
"type": "boolean",
"nullable": true,
"description": "Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified\n"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"avatar_url": {
"type": "string",
"deprecated": true,
"description": "Please use `image_url` instead"
},
"image_url": {
"type": "string",
"nullable": true
},
"username": {
"type": "string",
"nullable": true
},
"phone_number": {
"type": "string",
"nullable": true
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"label": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_oauth"
},
{
"$ref": "#/components/schemas/verification_google_one_tap"
}
],
"discriminator": {
"propertyName": "object"
}
}
},
"required": [
"object",
"id",
"provider",
"identification_id",
"provider_user_id",
"approved_scopes",
"email_address",
"first_name",
"last_name",
"public_metadata",
"created_at",
"updated_at",
"verification"
]
},
"SAMLConnection": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"domain": {
"type": "string",
"deprecated": true
},
"domains": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "boolean"
},
"provider": {
"type": "string"
},
"sync_user_attributes": {
"type": "boolean"
},
"allow_subdomains": {
"type": "boolean"
},
"allow_idp_initiated": {
"type": "boolean"
},
"disable_additional_identifications": {
"type": "boolean"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"id",
"name",
"active",
"provider",
"sync_user_attributes",
"created_at",
"updated_at"
],
"anyOf": [
{
"required": [
"domain"
]
},
{
"required": [
"domains"
]
}
]
},
"SAMLAccount": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"saml_account"
]
},
"provider": {
"type": "string"
},
"active": {
"type": "boolean"
},
"email_address": {
"type": "string"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"provider_user_id": {
"type": "string",
"nullable": true
},
"last_authenticated_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of last authentication.\n"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_saml"
},
{
"$ref": "#/components/schemas/verification_ticket"
}
],
"discriminator": {
"propertyName": "object"
}
},
"saml_connection": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/SAMLConnection"
}
]
}
},
"required": [
"id",
"object",
"provider",
"active",
"email_address",
"verification"
]
},
"EnterpriseConnection": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"protocol": {
"type": "string"
},
"provider": {
"type": "string"
},
"name": {
"type": "string"
},
"logo_public_url": {
"type": "string",
"nullable": true
},
"domain": {
"type": "string",
"deprecated": true
},
"domains": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "boolean"
},
"sync_user_attributes": {
"type": "boolean"
},
"allow_subdomains": {
"type": "boolean"
},
"allow_idp_initiated": {
"type": "boolean"
},
"disable_additional_identifications": {
"type": "boolean"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"id",
"protocol",
"name",
"logo_public_url",
"active",
"provider",
"sync_user_attributes",
"disable_additional_identifications",
"allow_subdomains",
"allow_idp_initiated",
"created_at",
"updated_at"
],
"anyOf": [
{
"required": [
"domain"
]
},
{
"required": [
"domains"
]
}
]
},
"EnterpriseAccount": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"enterprise_account"
]
},
"protocol": {
"type": "string",
"description": "The authentication protocol used to sign in.\n",
"enum": [
"oauth",
"saml"
]
},
"provider": {
"type": "string"
},
"active": {
"type": "boolean"
},
"email_address": {
"type": "string"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"provider_user_id": {
"description": "The unique ID of the user in the external provider's system",
"type": "string",
"nullable": true
},
"enterprise_connection_id": {
"type": "string",
"nullable": true
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"verification": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/verification_ticket"
},
{
"$ref": "#/components/schemas/verification_saml"
},
{
"$ref": "#/components/schemas/verification_oauth"
}
],
"discriminator": {
"propertyName": "object"
}
},
"enterprise_connection": {
"type": "object",
"nullable": true,
"oneOf": [
{
"$ref": "#/components/schemas/EnterpriseConnection"
}
]
},
"last_authenticated_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of last authentication.\n"
}
},
"required": [
"id",
"object",
"provider",
"active",
"email_address",
"verification"
]
},
"Organization": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"organization"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
},
"members_count": {
"type": "integer"
},
"missing_member_with_elevated_permissions": {
"type": "boolean"
},
"pending_invitations_count": {
"type": "integer"
},
"max_allowed_memberships": {
"type": "integer"
},
"admin_delete_enabled": {
"type": "boolean"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"additionalProperties": true
},
"created_by": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"last_active_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last activity.\n"
},
"role_set_key": {
"type": "string",
"description": "The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.\n",
"nullable": true
}
},
"required": [
"object",
"id",
"name",
"slug",
"has_image",
"max_allowed_memberships",
"admin_delete_enabled",
"public_metadata",
"created_at",
"updated_at"
]
},
"OrganizationMembershipPublicUserData": {
"description": "An organization membership with public user data populated",
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string",
"nullable": false
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"profile_image_url": {
"type": "string",
"nullable": true,
"deprecated": true
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
},
"identifier": {
"type": "string",
"nullable": true
},
"username": {
"type": "string",
"nullable": true
}
},
"required": [
"user_id",
"first_name",
"last_name",
"profile_image_url",
"image_url",
"has_image"
]
},
"OrganizationMembership": {
"description": "A user's membership in an organization",
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"organization_membership"
]
},
"role": {
"type": "string"
},
"role_name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, accessible from both Frontend and Backend APIs",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, accessible only from the Backend API",
"additionalProperties": true
},
"organization": {
"type": "object",
"nullable": false,
"allOf": [
{
"$ref": "#/components/schemas/Organization"
}
]
},
"public_user_data": {
"$ref": "#/components/schemas/OrganizationMembershipPublicUserData"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
}
},
"required": [
"object",
"id",
"role",
"permissions",
"public_metadata",
"created_at",
"updated_at",
"organization"
]
},
"User": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"user"
]
},
"external_id": {
"nullable": true,
"type": "string"
},
"primary_email_address_id": {
"nullable": true,
"type": "string"
},
"primary_phone_number_id": {
"nullable": true,
"type": "string"
},
"primary_web3_wallet_id": {
"nullable": true,
"type": "string"
},
"username": {
"nullable": true,
"type": "string"
},
"first_name": {
"nullable": true,
"type": "string"
},
"last_name": {
"nullable": true,
"type": "string"
},
"locale": {
"nullable": true,
"type": "string"
},
"profile_image_url": {
"type": "string",
"deprecated": true
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"private_metadata": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"unsafe_metadata": {
"type": "object",
"additionalProperties": true
},
"email_addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmailAddress"
}
},
"phone_numbers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PhoneNumber"
}
},
"web3_wallets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Web3Wallet"
}
},
"passkeys": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Passkey"
}
},
"password_enabled": {
"type": "boolean"
},
"two_factor_enabled": {
"type": "boolean"
},
"totp_enabled": {
"type": "boolean"
},
"backup_code_enabled": {
"type": "boolean"
},
"mfa_enabled_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled.\n",
"nullable": true
},
"mfa_disabled_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again.\n",
"nullable": true
},
"password_last_updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the user's password was last updated.\n",
"nullable": true
},
"external_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalAccountWithVerification"
}
},
"saml_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SAMLAccount"
}
},
"enterprise_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EnterpriseAccount"
}
},
"organization_memberships": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationMembership"
}
},
"last_sign_in_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of last sign-in.\n"
},
"banned": {
"type": "boolean",
"description": "Flag to denote whether user is banned or not.\n"
},
"locked": {
"type": "boolean",
"description": "Flag to denote whether user is currently locked, i.e. restricted from signing in or not.\n"
},
"lockout_expires_in_seconds": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.\n"
},
"verification_attempts_remaining": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"delete_self_enabled": {
"type": "boolean",
"description": "If enabled, user can delete themselves via FAPI.\n"
},
"create_organization_enabled": {
"type": "boolean",
"description": "If enabled, user can create organizations via FAPI.\n"
},
"create_organizations_limit": {
"type": "integer",
"description": "The maximum number of organizations the user can create. 0 means unlimited.\n",
"nullable": true
},
"last_active_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of the latest session activity, with day precision.\n",
"example": 1700690400000
},
"legal_accepted_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of when the user accepted the legal requirements.\n",
"example": 1700690400000
},
"bypass_client_trust": {
"type": "boolean",
"description": "When set to `true`, the user will bypass client trust checks during sign-in.",
"default": false
}
},
"required": [
"id",
"object",
"username",
"first_name",
"last_name",
"has_image",
"primary_email_address_id",
"primary_phone_number_id",
"primary_web3_wallet_id",
"password_enabled",
"two_factor_enabled",
"totp_enabled",
"backup_code_enabled",
"email_addresses",
"phone_numbers",
"web3_wallets",
"passkeys",
"external_accounts",
"saml_accounts",
"enterprise_accounts",
"public_metadata",
"external_id",
"last_sign_in_at",
"banned",
"locked",
"lockout_expires_in_seconds",
"verification_attempts_remaining",
"created_at",
"updated_at",
"delete_self_enabled",
"create_organization_enabled",
"last_active_at",
"mfa_enabled_at",
"mfa_disabled_at",
"legal_accepted_at"
]
},
"PasswordHasher": {
"type": "string",
"description": "The hashing algorithm that was used to generate the password digest.\n\nThe algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/),\n[`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/),\n[`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2),\n[`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html), the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`, and `sha512_symfony`, the SHA-512 variant of the [Symfony](https://symfony.com/doc/current/security/passwords.html) legacy hasher.\n\nEach of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information."
},
"TotalCount": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"total_count"
]
},
"total_count": {
"type": "integer",
"format": "int64"
}
},
"required": [
"object",
"total_count"
]
},
"CommerceMoneyResponse": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount in cents."
},
"amount_formatted": {
"type": "string",
"description": "The formatted amount as a string (e.g., \"$49.99\")."
},
"currency": {
"type": "string",
"description": "The currency code (e.g., \"USD\")."
},
"currency_symbol": {
"type": "string",
"description": "The currency symbol (e.g., \"$\")."
}
},
"required": [
"amount",
"amount_formatted",
"currency",
"currency_symbol"
]
},
"CommerceSubscriptionCreditResponse": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true,
"description": "Credit amount."
},
"cycle_remaining_percent": {
"type": "number",
"format": "float",
"description": "Percentage of the billing cycle remaining."
}
}
},
"FeatureResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"description",
"slug",
"avatar_url"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"feature"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the feature."
},
"name": {
"type": "string",
"description": "The name of the feature."
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the feature."
},
"slug": {
"type": "string",
"description": "The URL-friendly slug for the feature."
},
"avatar_url": {
"type": "string",
"nullable": true,
"description": "The URL of the feature's avatar image."
}
}
},
"CommercePlan": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"fee",
"annual_monthly_fee",
"annual_fee",
"description",
"product_id",
"is_default",
"is_recurring",
"publicly_visible",
"has_base_fee",
"for_payer_type",
"slug",
"avatar_url",
"free_trial_enabled",
"free_trial_days"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_plan"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the plan."
},
"name": {
"type": "string",
"description": "The name of the plan."
},
"fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"annual_monthly_fee": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true
},
"annual_fee": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true
},
"description": {
"type": "string",
"description": "The description of the plan.",
"nullable": true
},
"product_id": {
"type": "string",
"description": "The ID of the product this plan belongs to.",
"deprecated": true
},
"is_default": {
"type": "boolean",
"description": "Whether this is the default plan."
},
"is_recurring": {
"type": "boolean",
"description": "Whether this is a recurring plan."
},
"publicly_visible": {
"type": "boolean",
"description": "Whether this plan is publicly visible."
},
"has_base_fee": {
"type": "boolean",
"description": "Whether this plan has a base fee."
},
"for_payer_type": {
"type": "string",
"description": "The payer type this plan is designed for."
},
"slug": {
"type": "string",
"description": "The URL-friendly slug for the plan."
},
"avatar_url": {
"type": "string",
"description": "The URL of the plan's avatar image.",
"nullable": true
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FeatureResponse"
},
"description": "The features included in this plan."
},
"free_trial_enabled": {
"type": "boolean",
"description": "Whether free trial is enabled for this plan."
},
"free_trial_days": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Number of free trial days for this plan."
}
}
},
"CommercePaymentMethodResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"payer_id",
"payment_type",
"gateway",
"gateway_external_id",
"gateway_external_account_id",
"last4",
"status",
"card_type"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_payment_method"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the payment method."
},
"payer_id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"payment_type": {
"type": "string",
"description": "The payment method type.",
"enum": [
"card",
"link"
]
},
"is_default": {
"type": "boolean",
"description": "Whether this is the default payment method for the payer."
},
"gateway": {
"type": "string",
"description": "The payment gateway."
},
"gateway_external_id": {
"type": "string",
"description": "External ID in the payment gateway."
},
"gateway_external_account_id": {
"type": "string",
"nullable": true,
"description": "External account ID in the payment gateway."
},
"last4": {
"type": "string",
"description": "Last 4 digits of the card (for card payment methods).",
"nullable": true
},
"status": {
"type": "string",
"description": "Status of the payment method.",
"enum": [
"active",
"disconnected"
]
},
"wallet_type": {
"type": "string",
"description": "Type of wallet (if applicable).",
"nullable": true
},
"card_type": {
"type": "string",
"description": "Type of card (if applicable).",
"nullable": true
},
"expiry_year": {
"type": "integer",
"description": "Card expiration year (for card payment methods).",
"nullable": true
},
"expiry_month": {
"type": "integer",
"description": "Card expiration month (for card payment methods).",
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment method was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment method was last updated."
},
"is_removable": {
"type": "boolean",
"description": "Whether this payment method can be removed."
}
}
},
"CommerceSubscriptionItemNextPaymentResponse": {
"type": "object",
"additionalProperties": false,
"properties": {
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true,
"description": "Amount for the next payment."
},
"date": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) for the next payment date."
}
}
},
"CommercePayerResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_payer"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"instance_id": {
"type": "string",
"description": "Unique identifier for the Clerk instance."
},
"user_id": {
"type": "string",
"description": "User ID for user-type payers.",
"nullable": true
},
"first_name": {
"type": "string",
"description": "First name of the payer.",
"nullable": true
},
"last_name": {
"type": "string",
"description": "Last name of the payer.",
"nullable": true
},
"email": {
"type": "string",
"description": "Email address of the payer.",
"nullable": true
},
"organization_id": {
"type": "string",
"description": "Organization ID for org-type payers.",
"nullable": true
},
"organization_name": {
"type": "string",
"description": "Organization name for org-type payers.",
"nullable": true
},
"image_url": {
"type": "string",
"description": "URL of the payer's image/avatar."
},
"credits_balance": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "Current credits balance for the payer."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payer was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payer was last updated."
}
}
},
"CommerceSubscriptionItem": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"status",
"plan_id",
"plan_period",
"payer_id",
"is_free_trial",
"period_start",
"period_end",
"canceled_at",
"past_due_at",
"ended_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_subscription_item"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the subscription item."
},
"instance_id": {
"type": "string",
"description": "Unique identifier for the Clerk instance."
},
"status": {
"type": "string",
"description": "Current status of the subscription item.",
"enum": [
"active",
"canceled",
"expired",
"ended",
"past_due",
"upcoming",
"incomplete",
"abandoned"
]
},
"credit": {
"$ref": "#/components/schemas/CommerceSubscriptionCreditResponse",
"description": "Credit information (only available in PaymentAttempt events)."
},
"plan_id": {
"type": "string",
"description": "Unique identifier for the associated plan.",
"nullable": true
},
"price_id": {
"type": "string",
"description": "Unique identifier for the associated price"
},
"plan": {
"allOf": [
{
"$ref": "#/components/schemas/CommercePlan"
}
],
"nullable": true,
"description": "The associated plan."
},
"plan_period": {
"type": "string",
"description": "The billing period for this subscription item.",
"enum": [
"month",
"annual"
]
},
"payment_method": {
"$ref": "#/components/schemas/CommercePaymentMethodResponse",
"description": "The payment method used for this subscription item."
},
"lifetime_paid": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "Total amount paid over the lifetime of this subscription item."
},
"next_payment": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceSubscriptionItemNextPaymentResponse"
}
],
"nullable": true,
"description": "Information about the next payment."
},
"payer_id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"payer": {
"$ref": "#/components/schemas/CommercePayerResponse",
"description": "The payer associated with this subscription item."
},
"is_free_trial": {
"type": "boolean",
"description": "Whether this subscription item includes a free trial."
},
"period_start": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the current period started."
},
"period_end": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the current period ends."
},
"proration_date": {
"type": "string",
"format": "date",
"description": "The day the subscription item was prorated from. Only available in some responses."
},
"canceled_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription item was canceled."
},
"past_due_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription item became past due."
},
"ended_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription item ended."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the subscription item was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the subscription item was last updated."
}
}
},
"CommerceSubscriptionNextPayment": {
"type": "object",
"additionalProperties": false,
"required": [
"date",
"amount"
],
"properties": {
"date": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) of the next payment date."
},
"amount": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "The amount of the next payment."
}
}
},
"CommerceSubscription": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"status",
"payer_id",
"created_at",
"updated_at",
"active_at",
"past_due_at",
"subscription_items"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_subscription"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the commerce subscription."
},
"instance_id": {
"type": "string",
"description": "The ID of the instance this subscription belongs to."
},
"status": {
"type": "string",
"description": "The current status of the subscription.",
"enum": [
"active",
"past_due",
"canceled",
"ended",
"abandoned",
"incomplete"
]
},
"payer_id": {
"type": "string",
"description": "The ID of the payer for this subscription."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) of last update."
},
"active_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (milliseconds) when the subscription became active."
},
"past_due_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (milliseconds) when the subscription became past due."
},
"subscription_items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommerceSubscriptionItem"
},
"description": "Array of subscription items in this subscription."
},
"next_payment": {
"$ref": "#/components/schemas/CommerceSubscriptionNextPayment",
"description": "Information about the next scheduled payment."
},
"eligible_for_free_trial": {
"type": "boolean",
"description": "Whether the payer is eligible for a free trial."
}
}
},
"OAuthAccessToken": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"oauth_access_token"
]
},
"external_account_id": {
"type": "string",
"description": "External account ID"
},
"provider_user_id": {
"type": "string",
"description": "The unique ID of the user in the external provider's system"
},
"token": {
"type": "string",
"description": "The access token"
},
"expires_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of the access token expiration."
},
"provider": {
"type": "string",
"description": "The ID of the provider"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"label": {
"type": "string",
"nullable": true
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list of scopes that the token is valid for. Only present for OAuth 2.0 tokens."
},
"id_token": {
"type": "string",
"description": "The ID token retrieved from the OIDC provider. Only present for OIDC-compliant OAuth 2.0 providers when available."
},
"token_secret": {
"type": "string",
"description": "The token secret. Only present for OAuth 1.0 tokens."
}
},
"required": [
"object",
"external_account_id",
"provider_user_id",
"token",
"expires_at",
"provider",
"public_metadata",
"label"
]
}
},
"OrganizationMemberships": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationMembership"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization memberships\n"
}
},
"required": [
"data",
"total_count"
]
},
"OrganizationInvitationPublicUserData": {
"description": "An organization inviter's public user data",
"type": "object",
"additionalProperties": false,
"nullable": true,
"properties": {
"user_id": {
"type": "string",
"nullable": false
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
},
"identifier": {
"type": "string"
}
},
"required": [
"user_id",
"first_name",
"last_name",
"image_url",
"has_image",
"identifier"
]
},
"OrganizationInvitationPublicOrganizationData": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
}
},
"required": [
"id",
"name",
"slug",
"has_image"
]
},
"OrganizationInvitationWithPublicOrganizationData": {
"description": "An organization invitation with public organization data populated",
"type": "object",
"allOf": [
{
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"organization_invitation"
]
},
"id": {
"type": "string"
},
"email_address": {
"type": "string"
},
"role": {
"type": "string"
},
"role_name": {
"type": "string"
},
"organization_id": {
"type": "string"
},
"inviter_id": {
"type": "string",
"nullable": true
},
"public_inviter_data": {
"$ref": "#/components/schemas/OrganizationInvitationPublicUserData"
},
"status": {
"type": "string"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"additionalProperties": true
},
"url": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of expiration."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
}
}
},
{
"properties": {
"public_organization_data": {
"$ref": "#/components/schemas/OrganizationInvitationPublicOrganizationData"
}
}
}
],
"required": [
"object",
"id",
"email_address",
"role",
"role_name",
"public_metadata",
"url",
"expires_at",
"created_at",
"updated_at",
"inviter_id",
"public_inviter_data"
]
},
"OrganizationInvitationsWithPublicOrganizationData": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationInvitationWithPublicOrganizationData"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization invitations\n"
}
},
"required": [
"data",
"total_count"
]
},
"Invitation": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"invitation"
]
},
"id": {
"type": "string"
},
"email_address": {
"type": "string",
"format": "email"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"revoked": {
"type": "boolean",
"example": false
},
"status": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked",
"expired"
],
"example": "pending"
},
"url": {
"type": "string"
},
"expires_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of expiration.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"email_address",
"public_metadata",
"status",
"created_at",
"updated_at"
]
},
"AllowlistIdentifier": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"allowlist_identifier"
]
},
"id": {
"type": "string"
},
"invitation_id": {
"type": "string"
},
"identifier": {
"type": "string",
"description": "An email address or a phone number.\n"
},
"identifier_type": {
"type": "string",
"enum": [
"email_address",
"phone_number",
"web3_wallet"
]
},
"instance_id": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
}
},
"BlocklistIdentifier": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"blocklist_identifier"
]
},
"id": {
"type": "string"
},
"identifier": {
"type": "string",
"description": "An email address, email domain, phone number or web3 wallet.\n"
},
"identifier_type": {
"type": "string",
"enum": [
"email_address",
"phone_number",
"web3_wallet"
]
},
"instance_id": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
}
},
"BlocklistIdentifiers": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BlocklistIdentifier"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of blocklist identifiers\n"
}
},
"required": [
"data",
"total_count"
]
},
"ActorToken": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"actor_token"
]
},
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked"
]
},
"user_id": {
"type": "string"
},
"actor": {
"type": "object"
},
"token": {
"type": "string"
},
"url": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"user_id",
"actor",
"status",
"created_at",
"updated_at"
]
},
"CNameTarget": {
"type": "object",
"additionalProperties": false,
"properties": {
"host": {
"type": "string"
},
"value": {
"type": "string"
},
"required": {
"description": "Denotes whether this CNAME target is required to be set in order for the domain to be considered deployed.\n",
"type": "boolean"
}
},
"required": [
"host",
"value",
"required"
]
},
"Domain": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"domain"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"is_satellite": {
"type": "boolean"
},
"frontend_api_url": {
"type": "string"
},
"accounts_portal_url": {
"type": "string",
"nullable": true,
"description": "Null for satellite domains.\n"
},
"proxy_url": {
"type": "string",
"nullable": true
},
"development_origin": {
"type": "string"
},
"cname_targets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CNameTarget"
},
"nullable": true
}
},
"required": [
"object",
"id",
"name",
"is_satellite",
"frontend_api_url",
"development_origin"
]
},
"Domains": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Domain"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of domains\n"
}
},
"required": [
"data",
"total_count"
]
},
"Instance": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"instance"
]
},
"id": {
"type": "string"
},
"environment_type": {
"type": "string",
"example": "development"
},
"allowed_origins": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"example": [
"http://localhost:3000",
"https://some-domain"
]
}
},
"required": [
"object",
"id",
"environment_type",
"allowed_origins"
]
},
"InstanceRestrictions": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"instance_restrictions"
]
},
"allowlist": {
"type": "boolean"
},
"blocklist": {
"type": "boolean"
},
"allowlist_blocklist_disabled_on_sign_in": {
"type": "boolean"
},
"block_email_subaddresses": {
"type": "boolean"
},
"block_disposable_email_domains": {
"type": "boolean"
}
},
"required": [
"object",
"allowlist",
"blocklist",
"allowlist_blocklist_disabled_on_sign_in",
"block_email_subaddresses",
"block_disposable_email_domains"
]
},
"InstanceProtect": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"instance_protect"
]
},
"rules_enabled": {
"type": "boolean"
},
"specter_enabled": {
"type": "boolean"
}
},
"required": [
"object",
"rules_enabled",
"specter_enabled"
]
},
"OrganizationSettings": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"organization_settings"
]
},
"enabled": {
"type": "boolean"
},
"max_allowed_memberships": {
"type": "integer"
},
"max_allowed_roles": {
"type": "integer"
},
"max_role_sets_allowed": {
"type": "integer"
},
"max_allowed_permissions": {
"deprecated": true,
"description": "max_allowed_permissions is now a no-op, as permissions are now unlimited",
"type": "integer"
},
"creator_role": {
"type": "string",
"description": "The role key that a user will be assigned after creating an organization."
},
"admin_delete_enabled": {
"type": "boolean",
"description": "The default for whether an admin can delete an organization with the Frontend API."
},
"domains_enabled": {
"type": "boolean"
},
"slug_disabled": {
"type": "boolean"
},
"domains_enrollment_modes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"manual_invitation",
"automatic_invitation",
"automatic_suggestion"
]
}
},
"domains_default_role": {
"type": "string",
"description": "The role key that it will be used in order to create an organization invitation or suggestion."
},
"initial_role_set_key": {
"type": "string",
"nullable": true,
"description": "The role set key that it will be used to create new organizations."
}
},
"required": [
"object",
"enabled",
"max_allowed_memberships",
"max_allowed_roles",
"creator_role",
"admin_delete_enabled",
"domains_enabled",
"domains_enrollment_modes",
"domains_default_role"
]
},
"SvixURL": {
"type": "object",
"additionalProperties": false,
"properties": {
"svix_url": {
"type": "string"
}
},
"required": [
"svix_url"
]
},
"JWTTemplate": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"jwt_template"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"claims": {
"type": "object"
},
"lifetime": {
"type": "integer"
},
"allowed_clock_skew": {
"type": "integer"
},
"custom_signing_key": {
"type": "boolean"
},
"signing_algorithm": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"name",
"claims",
"lifetime",
"allowed_clock_skew",
"custom_signing_key",
"signing_algorithm",
"created_at",
"updated_at"
]
},
"MachineWithoutScopedMachines": {
"type": "object",
"required": [
"object",
"id",
"name",
"instance_id",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"enum": [
"machine"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the machine."
},
"name": {
"type": "string",
"description": "The name of the machine.",
"maxLength": 255,
"minLength": 1
},
"instance_id": {
"type": "string",
"description": "The ID of the instance this machine belongs to."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
},
"default_token_ttl": {
"type": "integer",
"description": "The default time-to-live (TTL) in seconds for tokens created by this machine.",
"minimum": 1,
"default": 3600
}
}
},
"Machine": {
"allOf": [
{
"$ref": "#/components/schemas/MachineWithoutScopedMachines"
},
{
"type": "object",
"required": [
"scoped_machines"
],
"properties": {
"scoped_machines": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MachineWithoutScopedMachines"
},
"description": "Array of machines this machine has access to."
}
}
}
]
},
"MachineScope": {
"type": "object",
"required": [
"object",
"from_machine_id",
"to_machine_id",
"created_at"
],
"properties": {
"object": {
"type": "string",
"enum": [
"machine_scope"
]
},
"from_machine_id": {
"type": "string",
"description": "The ID of the machine that has access to the target machine."
},
"to_machine_id": {
"type": "string",
"description": "The ID of the machine that is being accessed."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
}
}
},
"Organizations": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Organization"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organizations\n"
}
},
"required": [
"data",
"total_count"
]
},
"OrganizationWithLogo": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Organization"
},
{
"type": "object",
"properties": {
"logo_url": {
"type": "string",
"deprecated": true
},
"image_url": {
"type": "string"
},
"has_image": {
"type": "boolean"
}
},
"required": [
"image_url",
"has_image"
]
}
]
},
"OrganizationInvitation": {
"description": "An organization invitation",
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n",
"enum": [
"organization_invitation"
]
},
"id": {
"type": "string"
},
"email_address": {
"type": "string"
},
"role": {
"type": "string"
},
"role_name": {
"type": "string"
},
"organization_id": {
"type": "string"
},
"inviter_id": {
"type": "string",
"nullable": true
},
"public_inviter_data": {
"$ref": "#/components/schemas/OrganizationInvitationPublicUserData"
},
"status": {
"type": "string"
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"private_metadata": {
"type": "object",
"additionalProperties": true
},
"url": {
"type": "string",
"nullable": true
},
"expires_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of expiration."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
}
},
"required": [
"object",
"id",
"email_address",
"role",
"role_name",
"public_metadata",
"url",
"expires_at",
"created_at",
"updated_at",
"inviter_id",
"public_inviter_data"
]
},
"OrganizationInvitations": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationInvitation"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization invitations\n"
}
},
"required": [
"data",
"total_count"
]
},
"Permission": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"permission"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"key": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"name",
"key",
"description",
"type",
"created_at",
"updated_at"
]
},
"Role": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"role"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"key": {
"type": "string"
},
"description": {
"type": "string",
"nullable": true
},
"is_creator_eligible": {
"type": "boolean",
"description": "Whether this role is eligible to be an organization creator role"
},
"permissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"key",
"description",
"is_creator_eligible",
"permissions",
"created_at",
"updated_at"
]
},
"Roles": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Role"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of roles\n"
}
},
"required": [
"data",
"total_count"
]
},
"OrganizationDomainVerification": {
"description": "The verification object from an organization domain",
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Status of the verification. It can be `unverified` or `verified`",
"enum": [
"unverified",
"verified"
]
},
"strategy": {
"type": "string",
"description": "Name of the strategy used to verify the domain"
},
"attempts": {
"type": "integer",
"description": "How many attempts have been made to verify the domain",
"nullable": true
},
"expire_at": {
"type": "integer",
"nullable": true,
"format": "int64",
"description": "Unix timestamp of when the verification will expire"
}
},
"required": [
"status",
"strategy",
"attempts",
"expire_at"
]
},
"OrganizationDomain": {
"description": "An organization domain",
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value. Always `organization_domain`\n",
"enum": [
"organization_domain"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the organization domain"
},
"organization_id": {
"type": "string",
"description": "Unique identifier for the organization"
},
"name": {
"type": "string",
"description": "Name of the organization domain"
},
"enrollment_mode": {
"type": "string",
"description": "Mode of enrollment for the domain",
"enum": [
"manual_invitation",
"automatic_invitation",
"automatic_suggestion"
]
},
"affiliation_email_address": {
"type": "string",
"nullable": true,
"description": "Affiliation email address for the domain, if available."
},
"verification": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/OrganizationDomainVerification"
}
],
"description": "Verification details for the domain"
},
"total_pending_invitations": {
"type": "integer",
"format": "int32",
"description": "Total number of pending invitations associated with this domain"
},
"total_pending_suggestions": {
"type": "integer",
"format": "int32",
"description": "Total number of pending suggestions associated with this domain"
},
"public_organization_data": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/OrganizationInvitationPublicOrganizationData"
}
],
"description": "Public organization data associated with this domain"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp when the domain was created"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the last update to the domain"
}
},
"required": [
"object",
"id",
"organization_id",
"name",
"enrollment_mode",
"affiliation_email_address",
"verification",
"total_pending_invitations",
"total_pending_suggestions",
"created_at",
"updated_at"
]
},
"OrganizationDomains": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationDomain"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization domains\n"
}
},
"required": [
"data",
"total_count"
]
},
"ProxyCheck": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"proxy_check"
]
},
"id": {
"type": "string"
},
"domain_id": {
"type": "string"
},
"last_run_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of last run.\n"
},
"proxy_url": {
"type": "string"
},
"successful": {
"type": "boolean"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"domain_id",
"last_run_at",
"proxy_url",
"successful",
"created_at",
"updated_at"
]
},
"RedirectURL": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"redirect_url"
]
},
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"url",
"created_at",
"updated_at"
]
},
"SignInToken": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"sign_in_token"
]
},
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"pending",
"accepted",
"revoked"
]
},
"user_id": {
"type": "string"
},
"token": {
"type": "string"
},
"url": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"user_id",
"status",
"created_at",
"updated_at"
]
},
"SignUpVerification": {
"type": "object",
"nullable": true,
"additionalProperties": true,
"properties": {
"next_action": {
"type": "string",
"enum": [
"needs_prepare",
"needs_attempt",
""
]
},
"supported_strategies": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"SignUpVerifications": {
"type": "object",
"additionalProperties": false,
"properties": {
"email_address": {
"$ref": "#/components/schemas/SignUpVerification"
},
"phone_number": {
"$ref": "#/components/schemas/SignUpVerification"
},
"web3_wallet": {
"$ref": "#/components/schemas/SignUpVerification"
},
"external_account": {
"type": "object",
"nullable": true
}
},
"required": [
"email_address",
"phone_number",
"web3_wallet",
"external_account"
]
},
"SignUp": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"sign_up_attempt"
]
},
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"missing_requirements",
"complete",
"abandoned"
]
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"unverified_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"verifications": {
"$ref": "#/components/schemas/SignUpVerifications"
},
"username": {
"type": "string",
"nullable": true
},
"email_address": {
"type": "string",
"nullable": true
},
"phone_number": {
"type": "string",
"nullable": true
},
"web3_wallet": {
"type": "string",
"nullable": true
},
"password_enabled": {
"type": "boolean"
},
"first_name": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"unsafe_metadata": {
"type": "object",
"additionalProperties": true
},
"public_metadata": {
"type": "object",
"additionalProperties": true
},
"custom_action": {
"type": "boolean"
},
"external_id": {
"type": "string",
"nullable": true
},
"created_session_id": {
"type": "string",
"nullable": true
},
"created_user_id": {
"type": "string",
"nullable": true
},
"abandon_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp at which the user abandoned the sign up attempt.\n",
"example": 1700690400000
},
"legal_accepted_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp at which the user accepted the legal requirements.\n",
"example": 1700690400000
},
"locale": {
"type": "string",
"nullable": true,
"description": "The user locale preference for the sign-up specified as a BCP-47 language tag.",
"example": "en-US"
},
"external_account": {
"type": "object",
"deprecated": true
}
},
"required": [
"object",
"id",
"status",
"required_fields",
"optional_fields",
"missing_fields",
"unverified_fields",
"verifications",
"username",
"email_address",
"phone_number",
"web3_wallet",
"password_enabled",
"first_name",
"last_name",
"custom_action",
"external_id",
"created_session_id",
"created_user_id",
"abandon_at",
"legal_accepted_at"
]
},
"OAuthApplication": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"oauth_application"
]
},
"id": {
"type": "string"
},
"instance_id": {
"type": "string"
},
"name": {
"type": "string"
},
"client_id": {
"type": "string"
},
"client_uri": {
"type": "string",
"nullable": true
},
"client_image_url": {
"type": "string",
"nullable": true
},
"dynamically_registered": {
"type": "boolean"
},
"consent_screen_enabled": {
"type": "boolean"
},
"pkce_required": {
"type": "boolean"
},
"public": {
"type": "boolean"
},
"scopes": {
"type": "string"
},
"redirect_uris": {
"type": "array",
"items": {
"type": "string"
}
},
"callback_url": {
"type": "string",
"deprecated": true,
"description": "Deprecated: Use redirect_uris instead.\n"
},
"authorize_url": {
"type": "string"
},
"token_fetch_url": {
"type": "string"
},
"user_info_url": {
"type": "string"
},
"discovery_url": {
"type": "string"
},
"token_introspection_url": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"instance_id",
"name",
"dynamically_registered",
"consent_screen_enabled",
"pkce_required",
"public",
"client_id",
"client_uri",
"client_image_url",
"scopes",
"redirect_uris",
"callback_url",
"authorize_url",
"token_fetch_url",
"user_info_url",
"discovery_url",
"token_introspection_url",
"created_at",
"updated_at"
]
},
"OAuthApplications": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OAuthApplication"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of OAuth applications\n"
}
},
"required": [
"data",
"total_count"
]
},
"OAuthApplicationWithSecret": {
"allOf": [
{
"$ref": "#/components/schemas/OAuthApplication"
},
{
"type": "object",
"properties": {
"client_secret": {
"type": "string",
"description": "Empty if public client.\n"
}
}
}
]
},
"SAMLConnectionAttributeMapping": {
"type": "object",
"additionalProperties": false,
"properties": {
"user_id": {
"type": "string"
},
"email_address": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
}
},
"required": [
"user_id",
"email_address",
"first_name",
"last_name"
]
},
"schemas-SAMLConnection": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"saml_connection"
]
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"domain": {
"type": "string",
"deprecated": true
},
"domains": {
"type": "array",
"items": {
"type": "string"
}
},
"idp_entity_id": {
"type": "string",
"nullable": true
},
"idp_sso_url": {
"type": "string",
"nullable": true
},
"idp_certificate": {
"type": "string",
"nullable": true
},
"idp_metadata_url": {
"type": "string",
"nullable": true
},
"idp_metadata": {
"type": "string",
"nullable": true
},
"acs_url": {
"type": "string"
},
"sp_entity_id": {
"type": "string"
},
"sp_metadata_url": {
"type": "string"
},
"organization_id": {
"type": "string",
"nullable": true
},
"attribute_mapping": {
"$ref": "#/components/schemas/SAMLConnectionAttributeMapping"
},
"active": {
"type": "boolean"
},
"provider": {
"type": "string"
},
"user_count": {
"type": "integer"
},
"sync_user_attributes": {
"type": "boolean"
},
"allow_subdomains": {
"type": "boolean"
},
"allow_idp_initiated": {
"type": "boolean"
},
"disable_additional_identifications": {
"type": "boolean"
},
"force_authn": {
"type": "boolean",
"description": "Enable or deactivate ForceAuthn"
},
"enterprise_connection_id": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
}
},
"required": [
"object",
"id",
"name",
"idp_entity_id",
"idp_sso_url",
"idp_certificate",
"acs_url",
"sp_entity_id",
"sp_metadata_url",
"active",
"provider",
"user_count",
"sync_user_attributes",
"allow_subdomains",
"allow_idp_initiated",
"disable_additional_identifications",
"force_authn",
"created_at",
"updated_at"
],
"anyOf": [
{
"required": [
"domain"
]
},
{
"required": [
"domains"
]
}
]
},
"SAMLConnections": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/schemas-SAMLConnection"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of SAML Connections\n"
}
},
"required": [
"data",
"total_count"
]
},
"TestingToken": {
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"testing_token"
]
},
"token": {
"type": "string",
"description": "The actual token. This value is meant to be passed in the `__clerk_testing_token` query parameter with requests to the Frontend API.",
"example": "1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy"
},
"expires_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of the token's expiration time.\n",
"example": 1713880800
}
},
"required": [
"object",
"token",
"expires_at"
]
},
"WaitlistEntry": {
"type": "object",
"additionalProperties": false,
"properties": {
"object": {
"type": "string",
"enum": [
"waitlist_entry"
]
},
"id": {
"type": "string"
},
"email_address": {
"type": "string",
"format": "email"
},
"status": {
"type": "string",
"enum": [
"pending",
"invited",
"rejected",
"completed"
],
"example": "pending"
},
"is_locked": {
"type": "boolean",
"description": "Indicates if the waitlist entry is locked. Locked entries are being processed in a batch action and are unavailable for other actions.\n"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"invitation": {
"type": "object",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/Invitation"
}
]
}
},
"required": [
"object",
"id",
"email_address",
"status",
"created_at",
"updated_at"
]
},
"PaginatedCommercePlanResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommercePlan"
},
"description": "Array of plans."
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of plans."
}
}
},
"BillingPriceResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"plan_id",
"instance_id",
"currency",
"currency_symbol",
"amount",
"annual_monthly_amount",
"fee",
"annual_monthly_fee",
"created_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_price"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the price."
},
"plan_id": {
"type": "string",
"description": "Unique identifier for the associated plan."
},
"instance_id": {
"type": "string",
"description": "Unique identifier for the instance."
},
"currency": {
"type": "string",
"description": "The currency code (e.g., \"USD\")."
},
"currency_symbol": {
"type": "string",
"description": "The currency symbol (e.g., \"$\")."
},
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount in cents for the price."
},
"annual_monthly_amount": {
"type": "integer",
"format": "int64",
"description": "The monthly amount in cents when billed annually."
},
"fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"annual_monthly_fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"description": {
"type": "string",
"nullable": true,
"description": "The description of the price."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) of creation."
}
}
},
"PaginatedBillingPriceResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingPriceResponse"
},
"description": "Array of prices."
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of prices."
}
}
},
"CreateBillingPriceRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"plan_id",
"amount"
],
"properties": {
"plan_id": {
"type": "string",
"description": "The ID of the plan this price belongs to."
},
"currency": {
"type": "string",
"description": "The currency code (e.g., \"USD\"). Defaults to USD.",
"default": "USD"
},
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount in cents for the price. Must be at least $1 (100 cents)."
},
"annual_monthly_amount": {
"type": "integer",
"format": "int64",
"description": "The monthly amount in cents when billed annually. Optional."
},
"description": {
"type": "string",
"description": "An optional description for this custom price."
}
}
},
"PaginatedCommerceSubscriptionItemResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommerceSubscriptionItem"
},
"description": "Array of subscription items."
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of subscription items."
}
}
},
"ExtendFreeTrialRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"extend_to"
],
"properties": {
"extend_to": {
"type": "string",
"format": "date-time",
"description": "RFC3339 timestamp to extend the free trial to.\nMust be in the future and not more than 365 days from now.",
"example": "2026-01-08T00:00:00Z"
}
}
},
"schemas-FeatureResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"description",
"slug",
"avatar_url"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"feature"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the feature."
},
"name": {
"type": "string",
"description": "The name of the feature."
},
"description": {
"type": "string",
"description": "The description of the feature."
},
"slug": {
"type": "string",
"description": "The URL-friendly slug for the feature."
},
"avatar_url": {
"type": "string",
"description": "The URL of the feature's avatar image."
}
}
},
"schemas-CommercePlan": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"fee",
"annual_monthly_fee",
"annual_fee",
"amount",
"amount_formatted",
"annual_monthly_amount",
"annual_monthly_amount_formatted",
"annual_amount",
"annual_amount_formatted",
"currency_symbol",
"currency",
"description",
"product_id",
"is_default",
"is_recurring",
"publicly_visible",
"has_base_fee",
"payer_type",
"for_payer_type",
"slug",
"avatar_url",
"features"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_plan"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the commerce plan."
},
"name": {
"type": "string",
"description": "The name of the commerce plan."
},
"fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"annual_monthly_fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"annual_fee": {
"$ref": "#/components/schemas/CommerceMoneyResponse"
},
"amount": {
"type": "integer",
"format": "int64",
"description": "The amount in cents for the plan."
},
"amount_formatted": {
"type": "string",
"description": "The formatted amount as a string (e.g., \"$49.99\")."
},
"annual_monthly_amount": {
"type": "integer",
"format": "int64",
"description": "The monthly amount in cents when billed annually."
},
"annual_monthly_amount_formatted": {
"type": "string",
"description": "The formatted annual monthly amount as a string."
},
"annual_amount": {
"type": "integer",
"format": "int64",
"description": "The total annual amount in cents."
},
"annual_amount_formatted": {
"type": "string",
"description": "The formatted annual amount as a string."
},
"currency_symbol": {
"type": "string",
"description": "The currency symbol (e.g., \"$\")."
},
"currency": {
"type": "string",
"description": "The currency code (e.g., \"USD\")."
},
"description": {
"type": "string",
"description": "The description of the commerce plan."
},
"product_id": {
"type": "string",
"description": "The ID of the product this plan belongs to."
},
"is_default": {
"type": "boolean",
"description": "Whether this is the default plan."
},
"is_recurring": {
"type": "boolean",
"description": "Whether this is a recurring plan."
},
"publicly_visible": {
"type": "boolean",
"description": "Whether this plan is publicly visible."
},
"has_base_fee": {
"type": "boolean",
"description": "Whether this plan has a base fee."
},
"payer_type": {
"type": "array",
"items": {
"type": "string"
},
"description": "The types of payers that can use this plan."
},
"for_payer_type": {
"type": "string",
"description": "The payer type this plan is designed for."
},
"slug": {
"type": "string",
"description": "The URL-friendly slug for the plan."
},
"avatar_url": {
"type": "string",
"description": "The URL of the plan's avatar image."
},
"period": {
"type": "string",
"description": "The billing period for the plan."
},
"interval": {
"type": "integer",
"format": "int64",
"description": "The billing interval."
},
"features": {
"type": "array",
"items": {
"$ref": "#/components/schemas/schemas-FeatureResponse"
},
"description": "The features included in this plan."
},
"free_trial_enabled": {
"type": "boolean",
"description": "Whether free trial is enabled for this plan."
},
"free_trial_days": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Number of free trial days for this plan."
}
}
},
"CommercePaymentSourceResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"payer_id",
"payment_method",
"gateway",
"gateway_external_id",
"last4",
"status",
"wallet_type",
"card_type",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_source"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the payment source."
},
"payer_id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"payment_method": {
"type": "string",
"description": "The payment method type.",
"enum": [
"card",
"apple_pay",
"google_pay"
]
},
"is_default": {
"type": "boolean",
"nullable": true,
"description": "Whether this is the default payment source for the payer."
},
"gateway": {
"type": "string",
"description": "The payment gateway."
},
"gateway_external_id": {
"type": "string",
"description": "External ID in the payment gateway."
},
"gateway_external_account_id": {
"type": "string",
"nullable": true,
"description": "External account ID in the payment gateway."
},
"last4": {
"type": "string",
"description": "Last 4 digits of the card (for card payment sources)."
},
"status": {
"type": "string",
"description": "Status of the payment source.",
"enum": [
"active",
"disconnected"
]
},
"wallet_type": {
"type": "string",
"description": "Type of wallet (if applicable)."
},
"card_type": {
"type": "string",
"description": "Type of card (if applicable)."
},
"expiry_year": {
"type": "integer",
"description": "Card expiration year (for card payment sources)."
},
"expiry_month": {
"type": "integer",
"description": "Card expiration month (for card payment sources)."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment source was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment source was last updated."
},
"is_removable": {
"type": "boolean",
"nullable": true,
"description": "Whether this payment source can be removed."
}
}
},
"schemas-CommercePayerResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"first_name",
"last_name",
"email",
"image_url",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_payer"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"instance_id": {
"type": "string",
"description": "Unique identifier for the Clerk instance."
},
"user_id": {
"type": "string",
"description": "User ID for user-type payers."
},
"first_name": {
"type": "string",
"description": "First name of the payer."
},
"last_name": {
"type": "string",
"description": "Last name of the payer."
},
"email": {
"type": "string",
"description": "Email address of the payer."
},
"organization_id": {
"type": "string",
"description": "Organization ID for org-type payers."
},
"organization_name": {
"type": "string",
"description": "Organization name for org-type payers."
},
"image_url": {
"type": "string",
"description": "URL of the payer's image/avatar."
},
"credits_balance": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "Current credits balance for the payer."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payer was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payer was last updated."
}
}
},
"schemas-CommerceSubscriptionItem": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"status",
"plan_id",
"plan",
"plan_period",
"payment_source_id",
"payer_id",
"is_free_trial",
"proration_date",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_subscription_item"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the subscription item."
},
"instance_id": {
"type": "string",
"description": "Unique identifier for the Clerk instance."
},
"status": {
"type": "string",
"description": "Current status of the subscription item.",
"enum": [
"active",
"ended",
"past_due",
"upcoming",
"incomplete",
"abandoned"
]
},
"credit": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceSubscriptionCreditResponse"
}
],
"nullable": true,
"description": "Credit information (only available in PaymentAttempt events)."
},
"plan_id": {
"type": "string",
"description": "Unique identifier for the associated plan."
},
"price_id": {
"type": "string",
"description": "Unique identifier for the associated price"
},
"plan": {
"allOf": [
{
"$ref": "#/components/schemas/schemas-CommercePlan"
}
],
"nullable": true,
"description": "The associated commerce plan."
},
"plan_period": {
"type": "string",
"description": "The billing period for this subscription.",
"enum": [
"month",
"annual"
]
},
"payment_source_id": {
"type": "string",
"description": "Unique identifier for the payment source."
},
"payment_source": {
"allOf": [
{
"$ref": "#/components/schemas/CommercePaymentSourceResponse"
}
],
"nullable": true,
"description": "The payment source associated with this subscription."
},
"lifetime_paid": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true,
"description": "Total amount paid over the lifetime of this subscription."
},
"amount": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true,
"description": "Current amount for this subscription."
},
"next_invoice": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceSubscriptionItemNextPaymentResponse"
}
],
"nullable": true,
"description": "Information about the next invoice."
},
"next_payment": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceSubscriptionItemNextPaymentResponse"
}
],
"nullable": true,
"description": "Information about the next payment."
},
"payer_id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"payer": {
"allOf": [
{
"$ref": "#/components/schemas/schemas-CommercePayerResponse"
}
],
"nullable": true,
"description": "The payer associated with this subscription."
},
"is_free_trial": {
"type": "boolean",
"description": "Whether this subscription is currently on a free trial."
},
"period_start": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the current period started."
},
"period_end": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the current period ends."
},
"proration_date": {
"type": "string",
"description": "Date used for proration calculations."
},
"canceled_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription was canceled."
},
"past_due_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription became past due."
},
"ended_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the subscription ended."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the subscription was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the subscription was last updated."
}
}
},
"PriceTransitionRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"from_price_id",
"to_price_id"
],
"properties": {
"from_price_id": {
"type": "string",
"description": "The current price ID of the subscription item."
},
"to_price_id": {
"type": "string",
"description": "The target price ID to transition to."
}
}
},
"CommercePriceTransitionDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"previous_plan",
"previous_price",
"effective_at",
"effective_mode",
"charged_immediately",
"previous_subscription_item_status",
"previous_subscription_item_id"
],
"properties": {
"previous_plan": {
"$ref": "#/components/schemas/schemas-CommercePlan"
},
"previous_price": {
"$ref": "#/components/schemas/BillingPriceResponse"
},
"effective_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (milliseconds) when the new price takes effect."
},
"effective_mode": {
"type": "string",
"description": "When the new price takes effect.",
"enum": [
"immediate",
"end_of_period"
]
},
"next_billing_date": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (milliseconds) for the next billing date."
},
"charged_immediately": {
"type": "boolean",
"description": "Whether an immediate charge was made."
},
"immediate_charge": {
"allOf": [
{
"$ref": "#/components/schemas/CommerceMoneyResponse"
}
],
"nullable": true,
"description": "Amount charged immediately, if any."
},
"previous_subscription_item_status": {
"type": "string",
"description": "The status of the previous subscription item after transition.",
"enum": [
"canceled",
"ended",
"abandoned"
]
},
"previous_subscription_item_id": {
"type": "string",
"description": "The ID of the previous subscription item."
}
}
},
"CommercePriceTransitionResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"subscription_item",
"transition"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_price_transition"
]
},
"subscription_item": {
"$ref": "#/components/schemas/schemas-CommerceSubscriptionItem"
},
"transition": {
"$ref": "#/components/schemas/CommercePriceTransitionDetails"
}
}
},
"BillingPaymentAttempt": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"payment_id",
"instance_id",
"charge_type",
"payee_id",
"payee",
"payer_id",
"payer",
"amount",
"payment_method_id",
"payment_method",
"statement_id",
"gateway_external_id",
"gateway_external_url",
"status",
"paid_at",
"failed_at",
"created_at",
"updated_at"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_payment"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the payment attempt."
},
"payment_id": {
"type": "string",
"description": "Unique identifier for the associated payment."
},
"instance_id": {
"type": "string",
"description": "The ID of the instance this payment attempt belongs to."
},
"charge_type": {
"type": "string",
"description": "Type of charge for this payment attempt."
},
"payee_id": {
"type": "string",
"description": "Unique identifier for the payee."
},
"payee": {
"type": "object",
"description": "The payee associated with this payment attempt."
},
"payer_id": {
"type": "string",
"description": "Unique identifier for the payer."
},
"payer": {
"$ref": "#/components/schemas/CommercePayerResponse",
"description": "The payer associated with this payment attempt."
},
"subscription_item_id": {
"type": "string",
"description": "Unique identifier for the associated subscription item."
},
"subscription_item": {
"type": "object",
"description": "The subscription item associated with this payment attempt."
},
"amount": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "The amount for this payment attempt."
},
"payment_method_id": {
"type": "string",
"description": "Unique identifier for the payment method."
},
"payment_method": {
"$ref": "#/components/schemas/CommercePaymentMethodResponse",
"description": "The payment method used for this payment attempt."
},
"statement_id": {
"type": "string",
"description": "Unique identifier for the associated statement."
},
"gateway_external_id": {
"type": "string",
"description": "External identifier from the payment gateway.",
"nullable": true
},
"gateway_external_url": {
"type": "string",
"nullable": true,
"description": "External URL from the payment gateway."
},
"status": {
"type": "string",
"description": "The current status of the payment attempt.",
"enum": [
"pending",
"paid",
"failed"
]
},
"paid_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the payment was completed."
},
"failed_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp (in milliseconds) when the payment failed to be processed."
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment attempt was created."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the payment attempt was last updated."
}
}
},
"BillingStatement": {
"type": "object",
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"timestamp",
"payer",
"status",
"totals",
"groups"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_statement"
]
},
"id": {
"type": "string",
"description": "Unique identifier for the billing statement."
},
"instance_id": {
"type": "string",
"description": "The ID of the instance this statement belongs to."
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) when the statement was created."
},
"payer": {
"$ref": "#/components/schemas/CommercePayerResponse",
"description": "The payer associated with this statement."
},
"status": {
"type": "string",
"description": "The current status of the statement.",
"enum": [
"open",
"closed"
]
},
"totals": {
"type": "object",
"description": "Totals for the statement.",
"required": [
"grand_total",
"subtotal",
"tax_total"
],
"properties": {
"grand_total": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "The grand total amount for the statement."
},
"subtotal": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "The subtotal amount for the statement."
},
"tax_total": {
"$ref": "#/components/schemas/CommerceMoneyResponse",
"description": "The tax total amount for the statement."
}
}
},
"groups": {
"type": "array",
"description": "Array of statement groups.",
"items": {
"type": "object",
"description": "A statement group.",
"required": [
"object",
"timestamp",
"items"
],
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"commerce_statement_group"
]
},
"timestamp": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp (in milliseconds) of the date the group's payment attempts were created"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingPaymentAttempt"
},
"description": "The payment attempts included in the group"
}
}
}
}
}
},
"PaginatedBillingStatementResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingStatement"
},
"description": "Array of billing statements."
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of billing statements."
}
}
},
"PaginatedBillingPaymentAttemptResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BillingPaymentAttempt"
},
"description": "Array of billing payment attempts."
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of billing payment attempts."
}
}
},
"Permissions": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Permission"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of permissions\n"
}
},
"required": [
"data",
"total_count"
]
},
"RoleSetItem": {
"type": "object",
"description": "A role within a role set",
"properties": {
"object": {
"type": "string",
"enum": [
"role_set_item"
]
},
"id": {
"type": "string",
"description": "The unique identifier of the role"
},
"name": {
"type": "string",
"description": "The name of the role"
},
"key": {
"type": "string",
"description": "The key of the role (e.g., \"org:admin\", \"org:member\")"
},
"description": {
"type": "string",
"nullable": true,
"description": "Optional description of the role"
},
"members_count": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of members assigned to this role within the role set"
},
"has_members": {
"type": "boolean",
"nullable": true,
"description": "Whether this role has any members assigned within the role set"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of role creation"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last role update"
}
},
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"key",
"description",
"created_at",
"updated_at"
]
},
"RoleSetMigration": {
"type": "object",
"description": "Information about an ongoing role set migration",
"properties": {
"object": {
"type": "string",
"enum": [
"role_set_migration"
]
},
"id": {
"type": "string",
"description": "The unique identifier of the migration"
},
"organization_id": {
"type": "string",
"nullable": true,
"description": "The organization ID if the migration is scoped to a specific organization"
},
"instance_id": {
"type": "string",
"description": "The instance ID this migration belongs to"
},
"source_role_set_id": {
"type": "string",
"description": "The ID of the source role set being migrated from"
},
"dest_role_set_id": {
"type": "string",
"nullable": true,
"description": "The ID of the destination role set being migrated to"
},
"trigger_type": {
"type": "string",
"description": "What triggered this migration (e.g., \"role_set_deletion\", \"role_removal\")"
},
"status": {
"type": "string",
"description": "Current status of the migration (e.g., \"enqueued\", \"in_progress\", \"completed\")"
},
"migrated_members": {
"type": "integer",
"description": "Number of members that have been migrated so far"
},
"mappings": {
"type": "object",
"nullable": true,
"description": "Role key mappings from source to destination roles",
"additionalProperties": {
"type": "string"
}
},
"started_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp when the migration started"
},
"completed_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp when the migration completed"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of migration creation"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last migration update"
}
},
"additionalProperties": false,
"required": [
"object",
"id",
"instance_id",
"source_role_set_id",
"trigger_type",
"status",
"migrated_members",
"created_at",
"updated_at"
]
},
"RoleSet": {
"type": "object",
"description": "A role set defines a collection of roles that can be assigned to organization members",
"properties": {
"object": {
"type": "string",
"enum": [
"role_set"
]
},
"id": {
"type": "string",
"description": "The unique identifier of the role set"
},
"name": {
"type": "string",
"description": "The name of the role set"
},
"key": {
"type": "string",
"description": "A unique key for the role set (e.g., \"role_set:default\")"
},
"description": {
"type": "string",
"nullable": true,
"description": "Optional description of the role set"
},
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RoleSetItem"
},
"description": "The list of roles in this role set"
},
"default_role": {
"allOf": [
{
"$ref": "#/components/schemas/RoleSetItem"
}
],
"nullable": true,
"description": "The default role assigned to new organization members"
},
"creator_role": {
"allOf": [
{
"$ref": "#/components/schemas/RoleSetItem"
}
],
"nullable": true,
"description": "The role assigned to the creator of an organization"
},
"type": {
"type": "string",
"description": "The type of the role set (\"initial\" or \"custom\")",
"enum": [
"initial",
"custom"
]
},
"role_set_migration": {
"description": "Active migration information, only present when status is \"enqueued\" or \"in_progress\"",
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/RoleSetMigration"
}
]
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of role set creation"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last role set update"
}
},
"additionalProperties": false,
"required": [
"object",
"id",
"name",
"key",
"description",
"roles",
"type",
"created_at",
"updated_at"
]
},
"RoleSets": {
"type": "object",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RoleSet"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of role sets"
}
},
"required": [
"data",
"total_count"
]
},
"ReassignmentMappings": {
"type": "object",
"description": "Mappings from source role keys to destination role keys for role reassignment",
"additionalProperties": {
"type": "string"
}
}
},
"responses": {
"WellKnown.JWKS": {
"description": "Get the JSON Web Key Set",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JWKS"
}
}
}
},
"Client.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Client"
}
}
}
}
},
"ClerkErrors": {
"description": "Request was not successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"AuthenticationInvalid": {
"description": "Authentication invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"DeprecatedEndpoint": {
"description": "The endpoint is considered deprecated and is pending removal.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"UnprocessableEntity": {
"description": "Invalid request parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"Client": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Client"
}
}
}
},
"ResourceNotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"EmailAddress": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailAddress"
}
}
}
},
"AuthorizationInvalid": {
"description": "Authorization invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"DeletedObject": {
"description": "Deleted Object",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
}
}
}
},
"PhoneNumber": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PhoneNumber"
}
}
}
},
"Session.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
}
}
}
},
"Session": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Session"
}
}
}
},
"Session.Refresh": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SessionRefresh"
}
}
}
},
"Template.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Template"
}
}
}
}
},
"Template": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Template"
}
}
}
},
"PaymentRequired": {
"description": "Payment required",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"User.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
}
}
},
"User": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/User"
}
}
}
},
"User.Count": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TotalCount"
}
}
}
},
"CommerceSubscription": {
"description": "A commerce subscription.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommerceSubscription"
}
}
}
},
"OAuthAccessToken": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthAccessToken"
}
}
}
},
"OrganizationMemberships": {
"description": "A list of organization memberships",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationMemberships"
}
}
}
},
"OrganizationInvitationsWithPublicOrganizationData": {
"description": "A list of organization invitations with public organization data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationInvitationsWithPublicOrganizationData"
}
}
}
},
"Invitation.List": {
"description": "List of invitations",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Invitation"
}
}
}
}
},
"Invitation": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Invitation"
}
}
}
},
"Invitation.Revoked": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Invitation"
},
{
"type": "object",
"properties": {
"revoked": {
"type": "boolean",
"enum": [
true
],
"example": true
},
"status": {
"type": "string",
"enum": [
"revoked"
],
"example": "revoked"
}
}
}
]
}
}
}
},
"AllowlistIdentifier.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AllowlistIdentifier"
}
}
}
}
},
"AllowlistIdentifier": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AllowlistIdentifier"
}
}
}
},
"BlocklistIdentifier.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BlocklistIdentifiers"
}
}
}
},
"BlocklistIdentifier": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BlocklistIdentifier"
}
}
}
},
"InstanceSettings": {
"description": "InstanceSettings Server API",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.",
"enum": [
"instance_settings"
]
},
"id": {
"type": "string"
},
"restricted_to_allowlist": {
"type": "boolean"
},
"from_email_address": {
"type": "string"
},
"progressive_sign_up": {
"type": "boolean"
},
"enhanced_email_deliverability": {
"type": "boolean"
}
}
}
}
}
},
"ActorToken": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ActorToken"
}
}
}
},
"Domains": {
"description": "A list of domains",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Domains"
}
}
}
},
"Domain": {
"description": "A domain",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Domain"
}
}
}
},
"Instance": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Instance"
}
}
}
},
"InstanceRestrictions": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstanceRestrictions"
}
}
}
},
"InstanceProtect": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstanceProtect"
}
}
}
},
"OrganizationSettings": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationSettings"
}
}
}
},
"SvixURL": {
"description": "Response that contains a temporary Svix URL to access management dashboard",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SvixURL"
}
}
}
},
"JWTTemplate.List": {
"description": "List of JWT templates",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JWTTemplate"
}
}
}
}
},
"JWTTemplate": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JWTTemplate"
}
}
}
},
"Machine.List": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Machine"
}
},
"total_count": {
"type": "integer",
"description": "Total number of machines"
}
}
}
}
}
},
"Machine.Created": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Machine"
},
{
"type": "object",
"required": [
"secret_key"
],
"properties": {
"secret_key": {
"type": "string",
"readOnly": true,
"description": "The secret key for the machine, only returned upon creation."
}
}
}
]
}
}
}
},
"Machine": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Machine"
}
}
}
},
"Machine.Deleted": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"object",
"id",
"deleted"
],
"properties": {
"object": {
"type": "string",
"enum": [
"machine"
],
"description": "String representing the object's type."
},
"id": {
"type": "string",
"description": "The ID of the deleted machine"
},
"deleted": {
"type": "boolean",
"enum": [
true
],
"description": "Whether the machine was successfully deleted"
}
}
}
}
}
},
"Machine.SecretKey": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"object",
"secret"
],
"properties": {
"object": {
"type": "string",
"enum": [
"machine_secret_key"
],
"description": "String representing the object's type."
},
"secret": {
"type": "string",
"readOnly": true,
"description": "The secret key for the machine."
}
}
}
}
}
},
"MachineScope": {
"description": "Machine scope created successfully for a machine",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MachineScope"
}
}
}
},
"Conflict": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClerkErrors"
}
}
}
},
"MachineScope.Deleted": {
"description": "Machine scope deleted successfully for a machine",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"object",
"from_machine_id",
"to_machine_id",
"deleted"
],
"properties": {
"object": {
"type": "string",
"enum": [
"machine_scope"
],
"description": "String representing the object's type."
},
"from_machine_id": {
"type": "string",
"description": "The ID of the machine that had access to the target machine"
},
"to_machine_id": {
"type": "string",
"description": "The ID of the machine that was being accessed"
},
"deleted": {
"type": "boolean",
"enum": [
true
],
"description": "Whether the machine scope was successfully deleted"
}
}
}
}
}
},
"Organizations": {
"description": "A list of organizations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Organizations"
}
}
}
},
"Organization": {
"description": "An organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Organization"
}
}
}
},
"OrganizationWithLogo": {
"description": "An organization with a logo URL.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationWithLogo"
}
}
}
},
"OrganizationInvitations": {
"description": "A list of organization invitations",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationInvitations"
}
}
}
},
"OrganizationInvitation": {
"description": "An organization invitation",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationInvitation"
}
}
}
},
"Roles": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Roles"
}
}
}
},
"Role": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Role"
}
}
}
},
"OrganizationMembership": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationMembership"
}
}
}
},
"OrganizationDomains": {
"description": "A list of organization domains",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationDomains"
}
}
}
},
"OrganizationDomain": {
"description": "An organization domain",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationDomain"
}
}
}
},
"ProxyCheck": {
"description": "Health check information about a domain's proxy configuration validation attempt.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProxyCheck"
}
}
}
},
"RedirectURL.List": {
"description": "List of Redirect URLs",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RedirectURL"
}
}
}
}
},
"RedirectURL": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RedirectURL"
}
}
}
},
"SignInToken": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignInToken"
}
}
}
},
"SignUp": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignUp"
}
}
}
},
"OAuthApplications": {
"description": "A list of OAuth applications",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthApplications"
}
}
}
},
"OAuthApplicationWithSecret": {
"description": "An OAuth application with client secret",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthApplicationWithSecret"
}
}
}
},
"OAuthApplication": {
"description": "An OAuth application",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthApplication"
}
}
}
},
"SAMLConnections": {
"description": "A list of SAML Connections",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SAMLConnections"
}
}
}
},
"SAMLConnection": {
"description": "A SAML Connection",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schemas-SAMLConnection"
}
}
}
},
"TestingToken": {
"description": "A Testing Token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TestingToken"
}
}
}
},
"WaitlistEntries": {
"description": "List of waitlist entries",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WaitlistEntry"
}
},
"total_count": {
"type": "integer",
"description": "Total number of waitlist entries"
}
},
"required": [
"data",
"total_count"
]
}
}
}
},
"WaitlistEntry": {
"description": "A Waitlist Entry",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WaitlistEntry"
}
}
}
},
"WaitlistEntry.List": {
"description": "Array of waitlist entries",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WaitlistEntry"
}
}
}
}
},
"CommercePlan.List": {
"description": "A list of commerce plans.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedCommercePlanResponse"
}
}
}
},
"BillingPrice.List": {
"description": "A list of billing prices.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedBillingPriceResponse"
}
}
}
},
"BillingPrice": {
"description": "A billing price.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BillingPriceResponse"
}
}
}
},
"CommerceSubscriptionItem.List": {
"description": "A list of commerce subscription items.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedCommerceSubscriptionItemResponse"
}
}
}
},
"CommerceSubscriptionItem": {
"description": "A commerce subscription item.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommerceSubscriptionItem"
}
}
}
},
"responses-CommerceSubscriptionItem": {
"description": "A commerce subscription item.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/schemas-CommerceSubscriptionItem"
}
}
}
},
"CommercePriceTransition": {
"description": "A commerce price transition.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommercePriceTransitionResponse"
}
}
}
},
"BillingStatement.List": {
"description": "A list of billing statements.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedBillingStatementResponse"
}
}
}
},
"BillingStatement": {
"description": "A billing statement.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BillingStatement"
}
}
}
},
"BillingPaymentAttempt.List": {
"description": "A list of billing payment attempts.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PaginatedBillingPaymentAttemptResponse"
}
}
}
},
"Permissions": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Permissions"
}
}
}
},
"Permission": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Permission"
}
}
}
},
"RoleSets": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleSets"
}
}
}
},
"RoleSet": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RoleSet"
}
}
}
}
},
"parameters": {
"Paginated": {
"name": "paginated",
"in": "query",
"description": "Whether to paginate the results.\nIf true, the results will be paginated.\nIf false, the results will not be paginated.",
"required": false,
"schema": {
"type": "boolean"
}
},
"LimitParameter": {
"name": "limit",
"in": "query",
"description": "Applies a limit to the number of results returned.\nCan be used for paginating the results together with `offset`.",
"required": false,
"schema": {
"type": "integer",
"default": 10,
"minimum": 1,
"maximum": 500
}
},
"OffsetParameter": {
"name": "offset",
"in": "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`.",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"minimum": 0
}
}
}
},
"x-speakeasy-retries": {
"strategy": "backoff",
"backoff": {
"initialInterval": 500,
"maxInterval": 60000,
"maxElapsedTime": 3600000,
"exponent": 1.5
},
"statusCodes": [
"5XX"
],
"retryConnectionErrors": true
}
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment