vernonkeenan
/
lib
mirror of https://github.com/vernonkeenan/lib
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
lib/swagger/clerk.yaml

5350 lines
171 KiB
YAML
Raw Permalink Blame History

---
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.
Please see https://clerk.com/docs for more information.
version: v1
termsOfService: https://clerk.com/terms
license:
name: MIT
url: https://github.com/clerkinc/clerk-sdk-go/blob/main/LICENSE
externalDocs:
url: https://clerk.com/docs
servers:
- url: https://api.clerk.dev/v1
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
parameters:
LimitParameter:
name: limit
in: query
description: |-
Applies a limit to the number of results returned.
Can be used for paginating the results together with `offset`.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
required: false
schema:
type: number
default: 10
minimum: 1
maximum: 500
OffsetParameter:
name: offset
in: query
description: |-
Skip the first `offset` results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with `limit`.
required: false
schema:
type: number
default: 0
minimum: 0
schemas:
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.
"
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
last_active_organization_id:
type: string
nullable: true
last_active_at:
type: integer
expire_at:
type: integer
abandon_at:
type: integer
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
created_at:
type: integer
format: int64
description: "Unix timestamp of creation.
"
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.
"
enum:
- client
id:
type: string
description: "String representing the identifier of the session.
"
session_ids:
type: array
items:
type: string
sessions:
type: array
items:
"$ref": "#/components/schemas/Session"
sign_in_attempt_id:
type: string
nullable: true
deprecated: true
sign_up_attempt_id:
type: string
nullable: true
deprecated: true
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.
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
created_at:
type: integer
format: int64
description: "Unix timestamp of creation.
"
required:
- object
- id
- session_ids
- sessions
- sign_in_attempt_id
- sign_up_attempt_id
- sign_in_id
- sign_up_id
- last_active_session_id
- 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
required:
- errors
OTP:
type: object
additionalProperties: false
properties:
status:
type: string
enum:
- unverified
- verified
- failed
- expired
strategy:
type: string
enum:
- phone_code
- email_code
attempts:
type: integer
expire_at:
type: integer
required:
- status
- attempts
- strategy
- expire_at
Admin:
type: object
additionalProperties: false
properties:
status:
type: string
enum:
- verified
strategy:
type: string
enum:
- admin
attempts:
type: integer
nullable: true
expire_at:
type: integer
nullable: true
required:
- status
- strategy
IdentificationLink:
type: object
additionalProperties: false
properties:
type:
type: string
enum:
- oauth_google
- oauth_mock
id:
type: string
required:
- type
- id
EmailAddress:
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.
"
enum:
- email_address
email_address:
type: string
reserved:
type: boolean
verification:
type: object
nullable: true
oneOf:
- "$ref": "#/components/schemas/OTP"
- "$ref": "#/components/schemas/Admin"
linked_to:
type: array
items:
"$ref": "#/components/schemas/IdentificationLink"
required:
- object
- email_address
- verification
- linked_to
- reserved
DeletedObject:
type: object
additionalProperties: false
properties:
object:
type: string
id:
type: string
slug:
type: string
deleted:
type: boolean
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.
"
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/OTP"
- "$ref": "#/components/schemas/Admin"
linked_to:
type: array
items:
"$ref": "#/components/schemas/IdentificationLink"
backup_codes:
type: array
items:
type: string
nullable: true
required:
- object
- phone_number
- verification
- linked_to
- reserved
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.
"
enum:
- template
instance_id:
nullable: true
type: string
description: the id of the instance the template belongs to
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
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
delivered_by_clerk:
type: boolean
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
created_at:
type: integer
format: int64
description: "Unix timestamp of creation.
"
Web3Signature:
type: object
additionalProperties: false
properties:
status:
type: string
enum:
- verified
strategy:
type: string
enum:
- web3_metamask_signature
nonce:
type: string
enum:
- nonce
attempts:
type: integer
nullable: true
expire_at:
type: integer
nullable: true
required:
- status
- strategy
- nonce
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.
"
enum:
- web3_wallet
web3_wallet:
type: string
verification:
type: object
nullable: true
oneOf:
- "$ref": "#/components/schemas/Web3Signature"
- "$ref": "#/components/schemas/Admin"
required:
- object
- web3_wallet
- verification
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.
"
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
profile_image_url:
type: string
deprecated: true
image_url:
type: string
public_metadata:
type: object
private_metadata:
nullable: true
type: object
unsafe_metadata:
type: object
gender:
nullable: true
type: string
birthday:
nullable: true
type: string
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"
password_enabled:
type: boolean
two_factor_enabled:
type: boolean
totp_enabled:
type: boolean
backup_code_enabled:
type: boolean
external_accounts:
type: array
items:
type: object
last_sign_in_at:
type: integer
format: int64
nullable: true
description: "Unix timestamp of last sign-in.
"
banned:
type: boolean
description: "Flag to denote whether user is banned or not.
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
created_at:
type: integer
format: int64
description: "Unix timestamp of creation.
"
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.
"
enum:
- total_count
total_count:
type: integer
format: int64
required:
- object
- total_count
Organization:
type: object
properties:
object:
type: string
enum:
- organization
id:
type: string
name:
type: string
slug:
type: string
members_count:
type: integer
nullable: true
max_allowed_memberships:
type: integer
public_metadata:
type: object
private_metadata:
type: object
created_by:
type: string
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
- name
- slug
- max_allowed_memberships
- public_metadata
- private_metadata
- created_at
- updated_at
OrganizationMembership:
description: Hello world
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.
"
enum:
- organization_membership
role:
type: string
enum:
- admin
- basic_member
created_at:
type: integer
format: int64
description: Unix timestamp of creation.
updated_at:
type: integer
format: int64
description: Unix timestamp of last update.
organization:
type: object
nullable: false
allOf:
- "$ref": "#/components/schemas/Organization"
public_user_data:
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
nullable: true
identifier:
type: string
nullable: true
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
"
required:
- data
- total_count
Email:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- email
id:
type: string
slug:
type: string
nullable: true
from_email_name:
type: string
email_address_id:
type: string
nullable: true
to_email_address:
type: string
user_id:
type: string
nullable: true
subject:
type: string
body:
type: string
body_plain:
type: string
nullable: true
status:
type: string
data:
type: object
nullable: true
delivered_by_clerk:
type: boolean
required:
- object
- id
- from_email_name
- email_address_id
- to_email_address
- subject
- body
- status
- delivered_by_clerk
SMSMessage:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- sms_message
id:
type: string
slug:
type: string
nullable: true
from_phone_number:
type: string
to_phone_number:
type: string
phone_number_id:
type: string
nullable: true
user_id:
type: string
nullable: true
message:
type: string
status:
type: string
data:
type: object
nullable: true
delivered_by_clerk:
type: boolean
required:
- object
- id
- from_phone_number
- to_phone_number
- phone_number_id
- message
- status
- delivered_by_clerk
Invitation:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- invitation
id:
type: string
email_address:
type: string
format: email
public_metadata:
type: object
revoked:
type: boolean
example: true
status:
type: string
enum:
- pending
- accepted
- revoked
example: revoked
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
- 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.
"
enum:
- allowlist_identifier
id:
type: string
invitation_id:
type: string
identifier:
type: string
description: "An email address or a phone number.
"
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
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
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.
"
enum:
- blocklist_identifier
id:
type: string
identifier:
type: string
description:
"An email address, email domain, phone number or web3 wallet.
"
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
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
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
"
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
nullable: true
url:
type: string
nullable: true
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
- user_id
- actor
- status
- created_at
- updated_at
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
OrganizationSettings:
type: object
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
required:
- object
- enabled
- max_allowed_memberships
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.
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
required:
- object
- id
- name
- claims
- lifetime
- allowed_clock_skew
- created_at
- updated_at
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
"
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
required:
- logo_url
- image_url
OrganizationInvitation:
description: An organization invitation
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.
"
enum:
- organization_invitation
email_address:
type: string
role:
type: string
enum:
- admin
- basic_member
organization_id:
type: string
status:
type: string
created_at:
type: integer
format: int64
description: Unix timestamp of creation.
updated_at:
type: integer
format: int64
description: Unix timestamp of last update.
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
"
required:
- data
- total_count
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.
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
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.
"
updated_at:
type: integer
format: int64
description: "Unix timestamp of last update.
"
required:
- object
- id
- user_id
- status
- created_at
- updated_at
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:
type: object
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
public_metadata:
type: object
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
identification_requirements:
type: array
items:
type: array
items:
type: string
missing_requirements:
type: array
items:
type: string
email_address_verification:
type: object
nullable: true
deprecated: true
phone_number_verification:
type: object
nullable: true
deprecated: true
external_account_strategy:
type: string
nullable: true
external_account_verification:
type: object
nullable: true
deprecated: true
external_account:
type: object
required:
- object
- id
- status
- password_enabled
- custom_action
- abandon_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
scopes:
type: string
callback_url:
type: string
authorize_url:
type: string
token_fetch_url:
type: string
user_info_url:
type: string
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
- instance_id
- name
- client_id
- scopes
- callback_url
- authorize_url
- token_fetch_url
- user_info_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
"
required:
- data
- total_count
OAuthApplicationWithSecret:
allOf:
- "$ref": "#/components/schemas/OAuthApplication"
- type: object
properties:
client_secret:
type: string
required:
- client_secret
responses:
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"
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"
Session:
description: Success
content:
application/json:
schema:
"$ref": "#/components/schemas/Session"
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"
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"
OrganizationMemberships:
description: A list of organization memberships
content:
application/json:
schema:
"$ref": "#/components/schemas/OrganizationMemberships"
Email:
description: Success
content:
application/json:
schema:
"$ref": "#/components/schemas/Email"
SMSMessage:
description: Success
content:
application/json:
schema:
"$ref": "#/components/schemas/SMSMessage"
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"
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"
InstanceRestrictions:
description: Success
content:
application/json:
schema:
"$ref": "#/components/schemas/InstanceRestrictions"
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"
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"
OrganizationInvitation:
description: An organization invitation
content:
application/json:
schema:
"$ref": "#/components/schemas/OrganizationInvitation"
OrganizationInvitations:
description: A list of organization invitations
content:
application/json:
schema:
"$ref": "#/components/schemas/OrganizationInvitations"
OrganizationMembership:
description: Success
content:
application/json:
schema:
"$ref": "#/components/schemas/OrganizationMembership"
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"
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
to your application, by restricting access based on the user's email
address 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/reference/clerkjs/client
- name: Email Addresses
description:
A user can be associated with one or more email addresses and allows
them to be contacted via email.
externalDocs:
url: https://clerk.com/docs/reference/clerkjs/emailaddress
- name: Emails
description: |-
The email object represents an email that has been sent to an email address.
You can only send an email to email addresses that have been verified by a user.
Only recommended for transactional emails.
- 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
tied to authenticated sessions, enabling you to integrate with third-party
services.
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: 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: Phone Numbers
description:
A user can be associated with one or more email addresses and allows
them to be contacted via SMS.
externalDocs:
url: https://clerk.com/docs/reference/clerkjs/phonenumber
- name: Redirect URLs
description: |-
Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo).
In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs.
- name: Sessions
description: |-
The Session object is an abstraction over an HTTP session.
It models the period of information exchange between a user and the server.
Sessions are created when a user successfully goes through the sign in or sign up flows.
externalDocs:
url: https://clerk.com/docs/reference/clerkjs/session
- name: Sign-in Tokens
description: |-
Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials.
A sign-in token can be used at most once and they can be consumed from the Frontend API using the `ticket` strategy.
- name: SMS Messages
description: |-
SMS messages can be sent to verified phone numbers that belong to users.
This functionality is only recommended for transactional SMS messages.
- name: Users
description:
The user object represents a user that has successfully signed up to
your application.
externalDocs:
url: https://clerk.com/docs/reference/clerkjs/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.
paths:
"/public/demo_instance":
post:
security: []
operationId: CreateDemoInstance
summary: Create a demo development instance
description:
Creates a demo development instance and returns the corresponding
Frontend/Backend API keys.
tags:
- Miscellaneous
responses:
"200":
description: The API keys of the created instance.
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
object:
type: string
enum:
- demo_dev_instance
frontend_api_key:
type: string
backend_api_key:
type: string
jwt_verification_key:
type: string
description:
The public key that can be used to verify the session
tokens of the created instance.
accounts_url:
type: string
description:
The URL of the hosted Accounts Portal of the created
instance.
format: uri
"/public/interstitial":
get:
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.
It is used by Clerk SDKs when the user's authentication state cannot be immediately determined.
operationId: GetPublicInterstitial
tags:
- Miscellaneous
parameters:
- name: frontendApi
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
responses:
"200":
description: The interstitial page markup
"400":
description: A required query parameter is missing
"/jwks":
get:
operationId: 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":
description: The JSON Web Key Set
"/clients":
get:
operationId: GetClientList
tags:
- Clients
summary: List all clients
description: |-
Returns a list of all clients. The clients are returned sorted by creation date,
with the newest clients appearing first.
parameters:
- "$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"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/clients/verify":
post:
operationId: VerifyClient
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 Token that represents the active client.
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
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/{client_id}/last_active_session":
get:
operationId: GetClientLastActiveSession
tags:
- Clients
summary: Get the last active session of a client
description: Returns the details of the last active session of a client.
parameters:
- name: client_id
in: path
description: Client ID.
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"
"/email_addresses":
post:
operationId: CreateEmailAddress
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.
Default: false, unless it is the first email address.
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"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/email_addresses/{email_address_id}":
get:
operationId: GetEmailAddress
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
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
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
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
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
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
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
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
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
tags:
- Sessions
summary: List all sessions
description: |-
Returns a list of all sessions.
The sessions are returned sorted by creation date, with the newest sessions appearing first.
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/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"
"/sessions/{session_id}":
get:
operationId: GetSession
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}/revoke":
post:
operationId: RevokeSession
tags:
- Sessions
summary: Revoke a session
description: |-
Sets the status of a session as "revoked", which is an unauthenticated state.
In 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}/verify":
post:
operationId: VerifySession
tags:
- Sessions
summary: Verify a session
description:
Returns the session if it is authenticated, otherwise returns an
error.
parameters:
- name: session_id
in: path
description: The ID of the session
required: true
schema:
type: string
requestBody:
description: Parameters.
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
token:
type: string
description: |-
The JWT that is sent via the `__session` cookie from your frontend.
Note: this JWT must be associated with the supplied session ID.
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/{template_name}":
post:
operationId: CreateSessionTokenFromTemplate
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
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:
operationId: GetTemplateList
summary: List all templates
description: |-
Returns a list of all templates.
The 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
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:
operationId: GetTemplate
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:
operationId: UpsertTemplate
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.
Applicable 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.
For example, in the address 'hello@example.com', the local part is 'hello'.
Applicable 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"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/templates/{template_type}/{slug}/revert":
post:
operationId: RevertTemplate
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:
operationId: PreviewTemplate
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.
Applicable 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.
For example, in the address 'hello@example.com', the local part is 'hello'.
Applicable 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"
"/users":
get:
operationId: GetUserList
summary: List all users
description: |-
Returns a list of all users.
The 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.
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: external_id
in: query
schema:
type: array
items:
type: string
description: |-
Returns users with the specified external ids.
For each external id, the `+` and `-` can be
prepended to the id, which denote whether the
respective external id should be included or
excluded from the result set.
Accepts up to 100 external ids.
Any 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.
Accepts up to 100 usernames.
Any 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.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addressed 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.
For each user id, the `+` and `-` can be
prepended to the id, which denote whether the
respective user id should be included or
excluded from the result set.
Accepts up to 100 user ids.
Any 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 `-` can be
prepended to the id, which denote whether the
respective organization should be included or
excluded from the result set.
Accepts up to 100 organization ids.
required: false
- name: query
in: query
description: |-
Returns users that match the given query.
For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
The 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
- "$ref": "#/components/parameters/LimitParameter"
- "$ref": "#/components/parameters/OffsetParameter"
- name: order_by
in: query
description: |-
Allows to return users in a particular order.
At the moment, you can order the returned users either by their `created_at` or `updated_at` timestamp.
In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.
For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`.
If you don't use `+` or `-`, then `+` is implied.
Defaults to `-created_at`.
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
summary: Create a new user
description: |-
Creates a new user. Your user management settings determine how you should setup your user model.
Any email address and phone number created using this method will be marked as verified.
Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/import-users).
A rate limit rule of 20 requests per 10 seconds is applied to this endpoint.
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.
Must 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
email_address:
type: array
items:
type: string
description: |-
Email addresses to add to the user.
Must be unique across your instance.
The 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.
Must be unique across your instance.
The 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.
Must be unique across your instance.
The first wallet will be set as the user's primary wallet.
username:
type: string
description: |-
The username to give to the user.
It must be unique across your instance.
nullable: true
password:
type: string
description: |-
The plaintext password to give the user.
Must be at least 8 characters long, and can not 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.
The digests should be generated with one of the supported algorithms.
The hashing algorithm can be specified using the `password_hasher` property.
password_hasher:
type: string
description: |-
The hashing algorithm that was used to generate the password digest.
The algorithms we support at the moment are [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), md5, pbkdf2_sha256, [pbkdf2_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [scrypt_firebase](https://firebaseopensource.com/projects/firebase/scrypt/) and 2 [argon2](https://argon2.online/) variants, argon2i and argon2id.
Each of the above expects the incoming digest to be of a particular format.
More specifically:
**bcrypt:** The digest should be of the following form:
`$<algorithm version>$<cost>$<salt & hash>`
**md5:** The digest should follow the regular form e.g.:
`5f4dcc3b5aa765d61d8327deb882cf99`
**pbkdf2_sha256:** This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:
`pbkdf2_sha256$<iterations>$<salt>$<hash>`
Note: Both the salt and the hash are expected to be base64-encoded.
**pbkdf2_sha256_django:** This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):
`pbkdf2_sha256$<iterations>$<salt>$<hash>`
Note: The salt is expected to be un-encoded, the hash is expected base64-encoded.
**pbkdf2_sha1:** This is similar to pkbdf2_sha256_django, but with two differences:
1. uses sha1 instead of sha256
2. accepts the hash as a hex-encoded string
The format is the following:
`pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string>`
**scrypt_firebase:** The Firebase-specific variant of scrypt.
The value is expected to have 6 segments separated by the $ character and include the following information:
_hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase.
_salt:_ The salt used to generate the above hash. Again, this is given when exporting the user.
_signer key:_ The base64 encoded signer key.
_salt separator:_ The base64 encoded salt separator.
_rounds:_ The number of rounds the algorithm needs to run.
_memory cost:_ The cost of the algorithm run
The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase.
The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.
Once you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:
`<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>`
**argon2i:** Algorithms in the argon2 family generate digests that encode the following information:
_version (v):_ The argon version, version 19 is assumed
_memory (m):_ The memory used by the algorithm (in kibibytes)
_iterations (t):_ The number of iterations to perform
_parallelism (p):_ The number of threads to use
Parts are demarcated by the `$` character, with the first part identifying the algorithm variant.
The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism).
The final part is the actual digest.
`$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc`
**argon2id:** See the previous algorithm for an explanation of the formatting.
For the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`:
`$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU`
If you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support).
enum:
- bcrypt
- md5
- pbkdf2_sha256
- pbkdf2_sha256_django
- pbkdf2_sha1
- scrypt_firebase
- argon2i
- argon2id
skip_password_checks:
type: boolean
description: |-
When set to `true` all password checks are skipped.
It is recommended to use this method only when migrating plaintext passwords to Clerk.
Upon migration the user base should be prompted to pick stronger password.
skip_password_requirement:
type: boolean
description: |-
When set to `true`, `password` is not required anymore when creating the user and can be omitted.
This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords.
Please note that you cannot use this flag if password is the only way for a user to sign into your instance.
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.
Please note that currently the supported options are:
* Period: 30 seconds
* Code length: 6 digits
* Algorithm: SHA1
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.
You 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
private_metadata:
type: object
description:
Metadata saved on the user, that is only visible to
your Backend API
unsafe_metadata:
type: object
description: |-
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
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`).
responses:
"200":
"$ref": "#/components/responses/User"
"400":
"$ref": "#/components/responses/ClerkErrors"
"401":
"$ref": "#/components/responses/AuthenticationInvalid"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/users/count":
get:
operationId: GetUsersCount
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.
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: |-
Counts users with the specified phone numbers.
Accepts up to 100 phone numbers.
Any 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.
Accepts up to 100 external ids.
Any 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.
Accepts up to 100 usernames.
Any 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.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addressed 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.
Accepts up to 100 user ids.
Any user ids not found are ignored.
required: false
- name: query
in: query
description: |-
Counts users that match the given query.
For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
The 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
responses:
"200":
"$ref": "#/components/responses/User.Count"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/users/{user_id}":
get:
operationId: GetUser
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
summary: Update a user
description: |-
Update a user's attributes.
You 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.
Both IDs should correspond to verified identifications that belong to the user.
You can remove a user's username by setting the username attribute to null or the blank string "".
This is a destructive action; the identification will be deleted forever.
Usernames 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.
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.
Must 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
primary_email_address_id:
type: string
description: |-
The ID of the email address to set as primary.
It must be verified, and present on the current user.
primary_phone_number_id:
type: string
description: |-
The ID of the phone number to set as primary.
It must be verified, and present on the current user.
primary_web3_wallet_id:
type: string
description: |-
The ID of the web3 wallets to set as primary.
It must be verified, and present on the current user.
username:
type: string
description: |-
The username to give to the user.
It 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.
Must be at least 8 characters long, and can not be in any list of hacked passwords.
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.
Please note that currently the supported options are:
* Period: 30 seconds
* Code length: 6 digits
* Algorithm: SHA1
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.
You 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
private_metadata:
type: object
description:
Metadata saved on the user, that is only visible to
your Backend API
unsafe_metadata:
type: object
description: |-
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
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`).
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
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
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
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/{user_id}/metadata":
patch:
operationId: UpdateUserMetadata
summary: Merge and update a user's metadata
description: |-
Update a user's metadata attributes by merging existing values with the provided parameters.
This endpoint behaves differently than the *Update a user* endpoint.
Metadata values will not be replaced entirely.
Instead, a deep merge will be performed.
Deep means that any nested JSON objects will be merged as well.
You 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
description: |-
Metadata saved on the user, that is visible to both your frontend and backend.
The new object will be merged with the existing value.
private_metadata:
type: object
description: |-
Metadata saved on the user that is only visible to your backend.
The new object will be merged with the existing value.
unsafe_metadata:
type: object
description: |-
Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
The new object will be merged with the existing value.
Note: 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}/oauth_access_tokens/{provider}":
get:
operationId: 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.
For 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
responses:
"200":
description: The OAuth access token of the user, if any.
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: false
properties:
object:
type: string
token:
type: string
description: The access token
provider:
type: string
description: The ID of the provider
public_metadata:
type: object
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.
token_secret:
type: string
description: The token secret. Only present for OAuth 1.0 tokens.
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/users/{user_id}/organization_memberships":
get:
operationId: UsersGetOrganizationMemberships
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}/verify_password":
post:
operationId: VerifyPassword
summary: Verify the password of a user
description: |-
Check that the user's password matches the supplied input.
Useful 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
summary: Verify a TOTP or backup code for a user
description: |-
Verify that the provided TOTP or backup code is valid for the user.
Verifying a backup code will result it in being consumed (i.e. it will
become invalid).
Useful 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
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"
"/emails":
post:
operationId: CreateEmail
summary: Create an email
description: Create and send an email to the supplied email address ID.
tags:
- Emails
requestBody:
description: Required parameters
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
from_email_name:
type: string
description: |-
The email name portion of the sending email address.
<br/>e.g.: `from_email_name=info` will send from info@example.com
subject:
type: string
description: The subject of the email.
nullable: true
body:
type: string
description: The body of the email.
nullable: true
email_address_id:
type: string
nullable: true
description: The ID of the email address to send to.
template_slug:
type: string
nullable: true
description: The slug of the template to use for sending this email
responses:
"200":
"$ref": "#/components/responses/Email"
"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"
"/sms_messages":
post:
operationId: CreateSMSMessage
summary: Create an SMS message
description: Create and send an SMS message to the supplied phone number ID
tags:
- SMS Messages
requestBody:
description: Required parameters
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
message:
type: string
description: The message you would like to send
nullable: true
phone_number_id:
type: string
description:
The ID of a verified phone number the SMS message should
be sent to
responses:
"200":
"$ref": "#/components/responses/SMSMessage"
"400":
"$ref": "#/components/responses/ClerkErrors"
"401":
"$ref": "#/components/responses/AuthenticationInvalid"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"/invitations":
post:
operationId: CreateInvitation
summary: Create an invitation
description: |-
Creates a new invitation for the given email address and sends the invitation email.
Keep in mind that you cannot create an invitation if there is already one for the given email address.
Also, 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.
The value of this property should be a well-formed JSON object.
Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.
redirect_url:
type: string
description: |-
Optional URL which specifies where to redirect the user once they click the invitation link.
This 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.
required:
- email_address
responses:
"200":
"$ref": "#/components/responses/Invitation"
"400":
"$ref": "#/components/responses/ClerkErrors"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
get:
summary: List all invitations
description:
Returns all non-revoked invitations for your application, sorted
by creation date
operationId: ListInvitations
parameters:
- in: query
name: status
description: Filter invitations based on their status
required: false
schema:
type: string
enum:
- pending
- accepted
- revoked
tags:
- Invitations
responses:
"200":
"$ref": "#/components/responses/Invitation.List"
"/invitations/{invitation_id}/revoke":
post:
operationId: RevokeInvitation
summary: Revokes an invitation
description: |-
Revokes the given invitation.
Revoking an invitation will prevent the user from using the invitation link that was sent to them.
However, it doesn't prevent the user from signing up if they follow the sign up flow.
Only 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"
"400":
"$ref": "#/components/responses/ClerkErrors"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"/allowlist_identifiers":
get:
operationId: ListAllowlistIdentifiers
summary: List all identifiers on the allow-list
description: Get a list of all identifiers allowed to sign up to an instance
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
summary: Add identifier to the allow-list
description: Create an identifier allowed to sign up to an instance
tags:
- Allow-list / Block-list
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
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
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
summary: Add identifier to the block-list
description: Create an identifier that is blocked from accessing an instance
tags:
- Allow-list / Block-list
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
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
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.
Only alphanumeric values are allowed.
Note 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. Refer to
the [docs](https://clerk.com/docs/upgrade-guides/progressive-sign-up)
for more info.
nullable: true
session_token_template:
type: string
description:
The name of the JWT Template used to augment your session
tokens. To disable this, pass an empty string.
nullable: true
enhanced_email_deliverability:
type: boolean
description: |-
The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain.
This can be helpful if you do not have a high domain reputation.
nullable: true
test_mode:
type: boolean
description: |-
Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.
Defaults 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:
operationId: UpdateProductionInstanceDomain
summary: Update production instance domain
description: |-
Change the domain of a production instance.
Changing 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), updating your Social Connection's redirect URLs and setting the new keys in your code.
WARNING: 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
responses:
"202":
description: Accepted
"400":
"$ref": "#/components/responses/ClerkErrors"
"422":
"$ref": "#/components/responses/ClerkErrors"
"/actor_tokens":
post:
summary: Create actor token
description:
Create an actor token that can be used to impersonate the given
user.
operationId: CreateActorToken
tags:
- Actor Tokens
requestBody:
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
user_id:
type: string
description:
The ID of the user that can use the newly created sign
in token.
actor:
type: object
description: |-
The actor payload. It needs to include a sub property which should contain the ID of the actor.
This whole payload will be also included in the JWT session token.
expires_in_seconds:
type: integer
description: |-
Optional parameter to specify the life duration of the actor token in seconds.
By 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.
By 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:
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"
"/instance":
patch:
operationId: UpdateInstance
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.
Defaults 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
enhanced_email_deliverability:
type: boolean
description: |-
The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain.
This can be helpful if you do not have a high domain reputation.
nullable: true
support_email:
type: string
nullable: true
clerk_js_version:
type: string
nullable: true
development_origin:
type: string
nullable: true
experimental_allowed_origins:
type: array
items:
type: string
deprecated: true
allowed_origins:
type: array
items:
type: string
cookieless_dev:
type: boolean
description: |-
Whether the instance should operate in cookieless development mode (i.e. without third-party cookies).
Deprecated: Please use `url_based_session_syncing` instead.
deprecated: 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).
responses:
"204":
description: Accepted
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/instance/restrictions":
patch:
operationId: UpdateInstanceRestrictions
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
responses:
"200":
"$ref": "#/components/responses/InstanceRestrictions"
"402":
"$ref": "#/components/responses/PaymentRequired"
"/instance/organization_settings":
patch:
operationId: UpdateInstanceOrganizationSettings
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
responses:
"200":
"$ref": "#/components/responses/OrganizationSettings"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/webhooks/svix":
post:
operationId: 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
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
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:
summary: List all templates
operationId: ListJWTTemplates
tags:
- JWT Templates
responses:
"200":
"$ref": "#/components/responses/JWTTemplate.List"
post:
operationId: CreateJWTTemplate
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: number
minimum: 30
maximum: 315360000
description: JWT token lifetime
nullable: true
allowed_clock_skew:
type: number
minimum: 0
maximum: 300
description: JWT token allowed clock skew
nullable: true
custom_signing_key:
type: boolean
description:
Whether a custom signing key/algorithm is also provided
for this template
nullable: false
signing_algorithm:
type: string
description: The custom signing algorithm to use when minting JWTs
nullable: true
signing_key:
type: string
description:
The custom signing private key to use when minting
JWTs
nullable: true
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
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
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: number
minimum: 30
maximum: 315360000
description: JWT token lifetime
nullable: true
allowed_clock_skew:
type: number
minimum: 0
maximum: 300
description: JWT token allowed clock skew
nullable: true
custom_signing_key:
type: boolean
description:
Whether a custom signing key/algorithm is also provided
for this template
nullable: false
signing_algorithm:
type: string
description: The custom signing algorithm to use when minting JWTs
nullable: true
signing_key:
type: string
description:
The custom signing private key to use when minting
JWTs
nullable: true
responses:
"200":
"$ref": "#/components/responses/JWTTemplate"
"400":
"$ref": "#/components/responses/ClerkErrors"
"402":
"$ref": "#/components/responses/PaymentRequired"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
delete:
operationId: DeleteJWTTemplate
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"
"/organizations":
get:
operationId: ListOrganizations
summary: Get a list of organizations for an instance
description: |-
This request returns the list of organizations for an instance.
Results can be paginated using the optional `limit` and `offset` query parameters.
The organizations are ordered by descending creation date.
Most recent organizations will be returned first.
tags:
- Organizations
parameters:
- "$ref": "#/components/parameters/LimitParameter"
- "$ref": "#/components/parameters/OffsetParameter"
- 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: query
description: |-
Returns organizations with ID, name, or slug that match the given query.
Uses exact match for organization ID and partial match for name and slug.
schema:
type: string
responses:
"200":
"$ref": "#/components/responses/Organizations"
"400":
"$ref": "#/components/responses/ClerkErrors"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
post:
operationId: CreateOrganization
summary: Create an organization
description: |-
Creates a new organization with the given name for an instance.
In order to successfully create an organization you need to provide the ID of the User who will become the organization administrator.
You can specify an optional slug for the new organization.
If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-".
Organization slugs must be unique for the instance.
You can provide additional metadata for the organization and set any custom attribute you want.
Organizations support private and public metadata.
Private metadata can only be accessed from the Backend API.
Public metadata can be accessed from the Backend API, and are read-only from the Frontend API.
tags:
- Organizations
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: The name of the new organization
created_by:
type: string
description:
The ID of the User who will become the administrator
for the new organization
private_metadata:
type: object
description:
Metadata saved on the organization, accessible only
from the Backend API
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
slug:
type: string
description: |-
A slug for the new organization.
Can contain only lowercase alphanumeric characters and the dash "-".
Must be unique for the instance.
max_allowed_memberships:
type: integer
description:
The maximum number of memberships allowed for this
organization
required:
- name
- created_by
responses:
"200":
"$ref": "#/components/responses/Organization"
"400":
"$ref": "#/components/responses/ClerkErrors"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/organizations/{organization_id}":
get:
operationId: GetOrganization
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
responses:
"200":
"$ref": "#/components/responses/Organization"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"404":
"$ref": "#/components/responses/ResourceNotFound"
patch:
operationId: UpdateOrganization
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.
private_metadata:
type: object
description:
Metadata saved on the organization that is only visible
to your backend.
name:
type: string
description: The new name of the organization
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
description:
The maximum number of memberships allowed for this
organization
nullable: true
responses:
"200":
"$ref": "#/components/responses/Organization"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
delete:
operationId: DeleteOrganization
summary: Delete an organization
description: |-
Deletes the given organization.
Please note that deleting an organization will also delete all memberships and invitations.
This is not reversible.
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
summary: Merge and update metadata for an organization
description: |-
Update organization metadata attributes by merging existing values with the provided parameters.
Metadata values will be updated via a deep merge.
Deep meaning that any nested JSON objects will be merged as well.
You 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.
The new object will be merged with the existing value.
private_metadata:
type: object
description: |-
Metadata saved on the organization that is only visible to your backend.
The new object will be merged with the existing value.
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
summary: Upload a logo for the organization
description: |-
Set or replace an organization's logo, by uploading an image file.
This endpoint uses the `multipart/form-data` request content type and accepts a file of image type.
The file size cannot exceed 10MB.
Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/x-icon`, `image/vnd.microsoft.icon`.
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
file:
type: string
format: binary
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"
"/organizations/{organization_id}/invitations":
post:
operationId: CreateOrganizationInvitation
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.
You can specify the `role` for the invited organization member.
New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee.
The request body supports passing an optional `redirect_url` parameter.
When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided.
Use this parameter to implement a custom invitation acceptance flow.
You must specify the ID of the user that will send the invitation with the `inviter_user_id` parameter.
That user must be a member with administrator privileges in the organization.
Only "admin" members can create organization invitations.
You can optionally provide public metadata for the organization invitation.
These metadata are visible by both the Frontend and the Backend.
When 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:
required: true
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
description: |-
The ID of the user that invites the new member to the organization.
Must be an administrator in the organization.
role:
type: string
description: The role of the new member in the organization
enum:
- admin
- basic_member
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.
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.
required:
- email_address
- inviter_user_id
- 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"
"/organizations/{organization_id}/invitations/pending":
get:
operationId: ListPendingOrganizationInvitations
summary: Get a list of pending organization invitations
description: |-
This request returns the list of organization invitations with "pending" status.
These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet.
Results can be paginated using the optional `limit` and `offset` query parameters.
The organization invitations are ordered by descending creation date.
Most recent invitations will be returned first.
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}/revoke":
post:
operationId: RevokeOrganizationInvitation
summary: Revoke a pending organization invitation
description: |-
Use this request to revoke a previously issued organization invitation.
Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation.
Only organization invitations with "pending" status can be revoked.
The request needs the `requesting_user_id` parameter to specify the user which revokes the invitation.
Only 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: true
content:
application/json:
schema:
type: object
properties:
requesting_user_id:
type: string
description: |-
The ID of the user that revokes the invitation.
Must be an administrator in the organization.
required:
- requesting_user_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}/memberships":
post:
operationId: CreateOrganizationMembership
summary: Create a new organization membership
description: |-
Adds a user as a member to the given organization.
Only users in the same instance as the organization can be added as members.
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.
The 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.
enum:
- admin
- basic_member
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
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.
- "$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
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 the membership belongs to
- in: path
required: true
name: user_id
schema:
type: string
description: The ID of the user that this membership belongs to
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
role:
type: string
description: The new role of the given membership.
enum:
- admin
- basic_member
required:
- role
responses:
"200":
"$ref": "#/components/responses/OrganizationMembership"
"400":
"$ref": "#/components/responses/ClerkErrors"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
delete:
operationId: DeleteOrganizationMembership
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 the membership belongs to
- in: path
required: true
name: user_id
schema:
type: string
description: The ID of the user that this membership belongs to
responses:
"200":
"$ref": "#/components/responses/OrganizationMembership"
"400":
"$ref": "#/components/responses/ClerkErrors"
"401":
"$ref": "#/components/responses/AuthenticationInvalid"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"/organizations/{organization_id}/memberships/{user_id}/metadata":
patch:
operationId: UpdateOrganizationMembershipMetadata
summary: Merge and update organization membership metadata
description: |-
Update an organization membership's metadata attributes by merging existing values with the provided parameters.
Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well.
You 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 the membership belongs to
- in: path
required: true
name: user_id
schema:
type: string
description: The ID of the user that this membership belongs to
requestBody:
required: true
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.
The new object will be merged with the existing value.
private_metadata:
type: object
description: |-
Metadata saved on the organization membership that is only visible to your backend.
The new object will be merged with the existing value.
responses:
"200":
"$ref": "#/components/responses/OrganizationMembership"
"400":
"$ref": "#/components/responses/ClerkErrors"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
"/redirect_urls":
get:
summary: List all redirect URLs
description: Lists all whitelisted redirect_urls for the instance
operationId: ListRedirectURLs
tags:
- Redirect URLs
responses:
"200":
"$ref": "#/components/responses/RedirectURL.List"
post:
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"`
nullable: false
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
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
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
description: |-
Creates a new sign-in token and associates it with the given user.
By default, sign-in tokens expire in 30 days.
You 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.
By default, the duration is 30 days.
default: 2592000
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:
summary: Revoke the given sign-in token
description: Revokes a pending sign-in token
operationId: RevokeSignInToken
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}":
patch:
operationId: UpdateSignUp
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:
custom_action:
type: boolean
description: |-
Specifies whether a custom action has run for this sign-up attempt.
This is important when your instance has been configured to require a custom action to run before converting a sign-up into a user.
After executing any external business logic you deem necessary, you can mark the sign-up as ready-to-convert by setting `custom_action` to `true`.
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.
This will be copied to the resulting user when the sign-up is completed.
nullable: true
responses:
"200":
"$ref": "#/components/responses/SignUp"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"/oauth_applications":
get:
operationId: ListOAuthApplications
summary: Get a list of OAuth applications for an instance
description: |-
This request returns the list of OAuth applications for an instance.
Results can be paginated using the optional `limit` and `offset` query parameters.
The OAuth applications are ordered by descending creation date.
Most recent OAuth applications will be returned first.
tags:
- OAuth Applications
parameters:
- "$ref": "#/components/parameters/LimitParameter"
- "$ref": "#/components/parameters/OffsetParameter"
responses:
"200":
"$ref": "#/components/responses/OAuthApplications"
"400":
"$ref": "#/components/responses/ClerkErrors"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
post:
operationId: CreateOAuthApplication
summary: Create an OAuth application
description: |-
Creates a new OAuth application with the given name and callback URL for an instance.
The callback URL must be a valid url.
All 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
callback_url:
type: string
description: The callback URL of the new OAuth application
required:
- name
- callback_url
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
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
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
callback_url:
type: string
description: The new callback URL of the OAuth application
required:
- name
- callback_url
responses:
"200":
"$ref": "#/components/responses/OAuthApplication"
"403":
"$ref": "#/components/responses/AuthorizationInvalid"
"404":
"$ref": "#/components/responses/ResourceNotFound"
"422":
"$ref": "#/components/responses/UnprocessableEntity"
delete:
operationId: DeleteOAuthApplication
summary: Delete an OAuth application
description: |-
Deletes the given OAuth application.
This 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
summary: Rotate the client secret of the given OAuth application
description: |-
Rotates the OAuth application's client secret.
When 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"
Reference in New Issue View Git Blame Copy Permalink