Clerk Organization Creation Defaults API

openapi: 3.2.0
info:
  title: Clerk Frontend Organization Creation Defaults API
  version: v1
  description: 'The Clerk REST Frontend API, meant to be accessed from a browser or native environment.


    This is a Form Based API and all the data must be sent and formatted according to the `application/x-www-form-urlencoded` content type.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2021-02-05`. For more information, please see [Clerk API Versions](https://clerk.com/docs/backend-requests/versioning/overview).


    ### Using the Try It Console


    The `Try It` feature of the docs only works for **Development Instances** when using the `DevBrowser` security scheme.

    To use it, first generate a dev instance token from the `/v1/dev_browser` endpoint.


    Please see https://clerk.com/docs for more information.'
  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 Team
    url: https://clerk.com/support
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/javascript/blob/main/LICENSE
servers:
- url: https://{domain}.clerk.accounts.dev
  variables:
    domain:
      default: example-destined-camel-13
      description: Your Development Instance Frontend API Domain.
security:
- {}
- DevBrowser: []
- ProductionBrowser: []
- ProductionNativeApp: []
  ProductionNativeFlag: []
tags:
- name: Organization Creation Defaults
  description: Used to get suggested defaults when creating a new organization.
paths:
  /v1/me/organization_creation_defaults:
    get:
      operationId: getOrganizationCreationDefaults
      tags:
      - Organization Creation Defaults
      summary: Get Organization Creation Defaults
      description: 'Get suggested organization name and other defaults for creating a new organization.

        Returns suggestions based on the user''s email domain or configured naming templates.

        '
      responses:
        '200':
          description: Organization creation defaults
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      form:
                        type:
                        - object
                        - 'null'
                        properties:
                          name:
                            type:
                            - string
                            - 'null'
                            description: Suggested organization name
                          logo:
                            type:
                            - string
                            - 'null'
                            description: Suggested organization logo URL
                        description: Suggested form values for creating an organization
                      advisory:
                        type:
                        - object
                        - 'null'
                        properties:
                          type:
                            type: string
                            enum:
                            - warning
                            - error
                            - info
                            description: Type of advisory message
                          message:
                            type: string
                            description: Advisory message text
                        description: Advisory message if applicable (e.g., organization already exists)
                  client:
                    $ref: '#/components/schemas/Client.Client'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
components:
  schemas:
    Stubs.Verification.SAML:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_saml
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - saml
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type:
            - object
            - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Link:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_email_link
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - email_link
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        verified_at_client:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Client.Passkey:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - passkey
        name:
          type: string
        last_used_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp of when the passkey was last used.

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of update

            '
      required:
      - id
      - object
      - name
      - verification
    Stubs.SignInFactor:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
          - ticket
          - password
          - email_code
          - email_link
          - phone_code
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
          - totp
          - backup_code
          - oauth_apple
          - oauth_google
          - oauth_facebook
          - oauth_hubspot
          - oauth_github
          - oauth_mock
          - oauth_custom_mock
          - oauth_token_mock
          - saml
          - enterprise_sso
          - reset_password_email_code
          - reset_password_phone_code
          - passkey
          - google_one_tap
        safe_identifier:
          type: string
        enterprise_connection_id:
          type: string
        enterprise_connection_name:
          type: string
        email_address_id:
          type: string
        phone_number_id:
          type: string
        web3_wallet_id:
          type: string
        passkey_id:
          type: string
        primary:
          type:
          - boolean
          - 'null'
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.BackupCode:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_backup_code
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - backup_code
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.FromOauth:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_from_oauth
        status:
          type: string
          enum:
          - verified
          - unverified
        strategy:
          type: string
          enum:
          - from_oauth_apple
          - from_oauth_google
          - from_oauth_mock
          - from_oauth_custom_mock
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Token:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - token
        jwt:
          type: string
          description: 'String representing the encoded JWT value.

            '
      required:
      - object
      - jwt
    Stubs.Verification.Admin:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_admin
        status:
          type: string
          enum:
          - verified
          - unverified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - admin
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Client.SessionBase:
      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:
          - session
        status:
          type: string
          enum:
          - active
          - revoked
          - ended
          - expired
          - removed
          - abandoned
        expire_at:
          type: integer
          format: int64
        abandon_at:
          type: integer
          format: int64
        last_active_at:
          type: integer
          format: int64
        last_active_token:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Token'
        actor:
          type:
          - object
          - 'null'
          additionalProperties: true
      required:
      - id
      - object
      - status
      - expire_at
      - abandon_at
      - last_active_at
    Client.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
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Invitation'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
          - $ref: '#/components/schemas/Stubs.Verification.FromOauth'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        matches_sso_connection:
          description: 'Indicates whether this email address domain matches an active enterprise connection.

            '
          type: boolean
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - email_address
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    ExternalAccountWithVerification:
      type: object
      additionalProperties: true
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - external_account
          - facebook_account
          - google_account
        id:
          type: string
        provider:
          type: string
        identification_id:
          type: string
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
        approved_scopes:
          type: string
        email_address:
          type: string
        email_address_verified:
          type:
          - boolean
          - 'null'
          description: 'Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified

            '
        first_name:
          type: string
        last_name:
          type: string
        avatar_url:
          type: string
          deprecated: true
          description: Please use `image_url` instead
        image_url:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        public_metadata:
          type: object
          additionalProperties: true
        label:
          type:
          - string
          - 'null'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/verification_oauth'
          - $ref: '#/components/schemas/verification_google_one_tap'
          discriminator:
            propertyName: object
      required:
      - object
      - id
      - provider
      - identification_id
      - provider_user_id
      - approved_scopes
      - email_address
      - first_name
      - last_name
      - public_metadata
      - created_at
      - updated_at
      - verification
    Client.OrganizationMembership:
      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
        public_metadata:
          type: object
          additionalProperties: true
        role:
          type: string
        role_name:
          type: string
        permissions:
          type:
          - array
          - 'null'
          items:
            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.
        organization:
          $ref: '#/components/schemas/Client.Organization'
        public_user_data:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Client.PublicUserData'
      required:
      - object
      - id
      - public_metadata
      - role
      - role_name
      - permissions
      - created_at
      - updated_at
      - organization
    Client.PublicUserData:
      type: object
      additionalProperties: false
      properties:
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        image_url:
          type:
          - string
          - 'null'
        has_image:
          type: boolean
        identifier:
          type: string
        profile_image_url:
          type:
          - string
          - 'null'
          deprecated: true
          description: Use `image_url` instead.
        user_id:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        banned:
          type: boolean
      required:
      - first_name
      - last_name
      - identifier
      - has_image
    Client.SignIn:
      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:
          - sign_in_attempt
        id:
          type: string
        status:
          type: string
          enum:
          - abandoned
          - needs_identifier
          - needs_first_factor
          - needs_second_factor
          - needs_client_trust
          - needs_new_password
          - needs_protect_check
          - complete
        supported_identifiers:
          type: array
          description: List of supported identifiers that can be used to sign in.
          items:
            type: string
            enum:
            - email_address
            - phone_number
            - username
            - web3_wallet
            - passkey
        supported_first_factors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
        supported_second_factors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
        first_factor_verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Password'
          - $ref: '#/components/schemas/Stubs.Verification.Oauth'
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Web3Signature'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
          - $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap'
        second_factor_verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.TOTP'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.BackupCode'
        identifier:
          type:
          - string
          - 'null'
        user_data:
          type:
          - object
          - 'null'
          additionalProperties: false
          properties:
            first_name:
              type:
              - string
              - 'null'
            last_name:
              type:
              - string
              - 'null'
            image_url:
              type: string
            has_image:
              type: boolean
            profile_image_url:
              type:
              - string
              - 'null'
              deprecated: true
              description: Use `image_url` instead.
          required:
          - first_name
          - last_name
          - has_image
        created_session_id:
          type:
          - string
          - 'null'
        abandon_at:
          type: integer
          format: int64
          description: Unix timestamp at which the sign in will be abandoned.
          example: 1700690400000
        client_trust_state:
          type:
          - string
          - 'null'
          description: 'The trust state of the client for this sign-in attempt. - `pending`: The identifier has not been set yet. - `new`: The user has not had a session on this client before. - `known`: The user has had a session on this client before.

            '
          enum:
          - pending
          - new
          - known
      required:
      - object
      - id
      - status
      - supported_identifiers
      - supported_first_factors
      - supported_second_factors
      - first_factor_verification
      - second_factor_verification
      - identifier
      - user_data
      - created_session_id
      - abandon_at
    verification_oauth:
      x-speakeasy-name-override: Oauth
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_oauth
        status:
          type: string
          x-speakeasy-unknown-values: allow
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          x-speakeasy-unknown-values: allow
          pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$
        external_verification_redirect_url:
          type: string
        error:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/ClerkError'
        expire_at:
          type: integer
        attempts:
          type:
          - integer
          - 'null'
        verified_at_client:
          type:
          - string
          - 'null'
      required:
      - status
      - strategy
      - attempts
      - expire_at
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    Stubs.Verification.Ticket:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_ticket
        status:
          type: string
          enum:
          - unverified
          - verified
          - expired
        strategy:
          type: string
          enum:
          - ticket
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Passkey:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_passkey
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - passkey
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        nonce:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Stubs.Verification.Web3Signature:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_web3
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        nonce:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
      required:
      - status
      - strategy
    Client.User:
      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:
          - user
        username:
          type:
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        image_url:
          type: string
        has_image:
          type: boolean
        primary_email_address_id:
          type:
          - string
          - 'null'
        primary_phone_number_id:
          type:
          - string
          - 'null'
        primary_web3_wallet_id:
          type:
          - string
          - 'null'
        password_enabled:
          type: boolean
        two_factor_enabled:
          type: boolean
        totp_enabled:
          type: boolean
        backup_code_enabled:
          type: boolean
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/Client.EmailAddress'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/Client.PhoneNumber'
        web3_wallets:
          type: array
          items:
            $ref: '#/components/schemas/Client.Web3Wallet'
        passkeys:
          type: array
          items:
            $ref: '#/components/schemas/Client.Passkey'
        organization_memberships:
          type: array
          items:
            $ref: '#/components/schemas/Client.OrganizationMembership'
        external_accounts:
          type: array
          items:
            $ref: '#/components/schemas/ExternalAccountWithVerification'
        saml_accounts:
          type: array
          items:
            $ref: '#/components/schemas/Client.SAMLAccount'
        password_last_updated_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of last update.
          example: 1700690400000
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        unsafe_metadata:
          type: object
          additionalProperties: true
        external_id:
          type:
          - string
          - 'null'
        last_sign_in_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of last sign-in.
          example: 1700690400000
        banned:
          type: boolean
          description: Flag to denote whether user is banned or not.
        locked:
          type: boolean
          description: 'Flag to denote whether user is currently locked, i.e. restricted from signing in or not.

            '
        deprovisioned:
          type: boolean
          description: 'Flag to denote whether the user has been deprovisioned via SCIM and is restricted from signing in. Only present on instances with SCIM enabled.

            '
        lockout_expires_in_seconds:
          type:
          - integer
          - 'null'
          format: int64
          description: 'The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.

            '
          example: 300
        verification_attempts_remaining:
          type:
          - integer
          - 'null'
          format: int64
          description: 'The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.

            '
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
          example: 1700690400000
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
          example: 1700690400000
        delete_self_enabled:
          type: boolean
          description: If enabled, user can delete themselves via FAPI.
        create_organization_enabled:
          type: boolean
          description: If enabled, user can create organizations via FAPI.
        create_organizations_limit:
          type: integer
          description: The maximum number of organizations the user can create. 0 means unlimited.
        last_active_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of the latest session activity, with day precision.
          example: 1700690400000
        mfa_enabled_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user enabled MFA.
          example: 1700690400000
        mfa_disabled_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user disabled MFA.
          example: 1700690400000
        legal_accepted_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user accepted the legal requirements.
          example: 1700690400000
        profile_image_url:
          type: string
          deprecated: true
          description: Deprecated. Use `image_url` instead.
      required:
      - id
      - object
      - username
      - first_name
      - last_name
      - has_image
      - primary_email_address_id
      - primary_phone_number_id
      - primary_web3_wallet_id
      - password_enabled
      - two_factor_enabled
      - totp_enabled
      - backup_code_enabled
      - email_addresses
      - phone_numbers
      - web3_wallets
      - passkeys
      - external_accounts
      - saml_accounts
      - enterprise_accounts
      - public_metadata
      - external_id
      - last_sign_in_at
      - banned
      - locked
      - lockout_expires_in_seconds
      - verification_attempts_remaining
      - created_at
      - updated_at
      - delete_self_enabled
      - create_organization_enabled
      - last_active_at
      - mfa_enabled_at
      - mfa_disabled_at
      - legal_accepted_at
    Stubs.Verification.Oauth:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_oauth
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z0-9_]+$
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        error:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/ClerkError'
        expire_at:
          type: integer
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
      - expire_at
    Client.Organization:
      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:
          - org

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-organization-creation-defaults-api-openapi.yml