Clerk Sessions API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Sessions 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.


    ### 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. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions).


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: 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/references/javascript/session
paths:
  /sessions:
    get:
      operationId: GetSessionList
      x-speakeasy-group: sessions
      x-speakeasy-name-override: list
      tags:
      - Sessions
      summary: List All Sessions
      description: 'Returns a list of sessions matching the provided criteria.

        The sessions are returned sorted by creation date, with the newest sessions appearing first.


        Note: This endpoint does not return all sessions that have ever existed. Old and inactive sessions are periodically cleaned up and will not be included in the results.


        **Deprecation Notice (2024-01-01):** All parameters were initially considered optional, however

        moving forward at least one of `client_id` or `user_id` parameters should be provided.'
      parameters:
      - name: client_id
        in: query
        required: false
        description: List sessions for the given client
        schema:
          type: string
      - name: user_id
        in: query
        required: false
        description: List sessions for the given user
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter sessions by the provided status
        schema:
          type: string
          enum:
          - abandoned
          - active
          - ended
          - expired
          - removed
          - replaced
          - revoked
      - $ref: '#/components/parameters/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/Session.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: createSession
      x-speakeasy-group: sessions
      x-speakeasy-name-override: create
      tags:
      - Sessions
      summary: Create a New Active Session
      description: 'Create a new active session for the provided user ID.


        **This operation is intended only for use in testing, and is not available for production instances.** If you are looking to generate a user session from the backend,

        we recommend using the [Sign-in Tokens](https://clerk.com/docs/reference/backend-api/tag/Sign-in-Tokens#operation/CreateSignInToken) resource instead.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: The ID representing the user
                active_organization_id:
                  type: string
                  description: The ID of the organization to set as active for this session
              required:
              - user_id
      responses:
        '200':
          $ref: '#/components/responses/Session'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /sessions/{session_id}:
    get:
      operationId: GetSession
      x-speakeasy-group: sessions
      x-speakeasy-name-override: get
      tags:
      - Sessions
      summary: Retrieve a Session
      description: Retrieve the details of a session
      parameters:
      - name: session_id
        in: path
        description: The ID of the session
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Session'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /sessions/{session_id}/refresh:
    post:
      operationId: RefreshSession
      x-speakeasy-group: sessions
      x-speakeasy-name-override: refresh
      tags:
      - Sessions
      summary: Refresh a Session
      description: 'Refreshes a session by creating a new session token. A 401 is returned when there

        are validation errors, which signals the SDKs to fall back to the handshake flow.'
      parameters:
      - name: session_id
        in: path
        description: The ID of the session
        required: true
        schema:
          type: string
      requestBody:
        description: Refresh session parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                expired_token:
                  type: string
                  description: 'The JWT that is sent via the `__session` cookie from your frontend.

                    Note: this JWT must be associated with the supplied session ID.'
                refresh_token:
                  type: string
                  description: The refresh token from the `__refresh` cookie set via FAPI's handshake flow.
                request_origin:
                  type: string
                  description: The origin of the request.
                request_headers:
                  type: object
                  additionalProperties: true
                  description: The headers of the request.
                  nullable: true
                format:
                  type: string
                  description: The format of the response.
                  nullable: true
                  default: token
                  enum:
                  - token
                  - cookie
                request_originating_ip:
                  type: string
                  description: The IP address of the request.
                  nullable: true
              required:
              - expired_token
              - refresh_token
              - request_origin
      responses:
        '200':
          $ref: '#/components/responses/Session.Refresh'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
  /sessions/{session_id}/revoke:
    post:
      operationId: RevokeSession
      x-speakeasy-group: sessions
      x-speakeasy-name-override: revoke
      tags:
      - Sessions
      summary: Revoke a Session
      description: 'Sets the status of a session as "revoked", which is an unauthenticated state.

        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}/tokens:
    post:
      operationId: CreateSessionToken
      x-speakeasy-group: sessions
      x-speakeasy-name-override: createToken
      tags:
      - Sessions
      summary: Create a Session Token
      description: Creates a session JSON Web Token (JWT) based on a session.
      parameters:
      - name: session_id
        in: path
        description: The ID of the session
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expires_in_seconds:
                  type: integer
                  minimum: 30
                  maximum: 315360000
                  description: Use this parameter to override the default session token lifetime.
                  nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - token
                  jwt:
                    type: string
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /sessions/{session_id}/tokens/{template_name}:
    post:
      operationId: CreateSessionTokenFromTemplate
      x-speakeasy-group: sessions
      x-speakeasy-name-override: createTokenFromTemplate
      tags:
      - Sessions
      summary: Create a Session Token from a JWT Template
      description: Creates a JSON Web Token (JWT) based on a session and a JWT Template name defined for your instance
      parameters:
      - name: session_id
        in: path
        description: The ID of the session
        required: true
        schema:
          type: string
      - name: template_name
        in: path
        description: The name of the JWT template defined in your instance (e.g. `custom_hasura`).
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                expires_in_seconds:
                  type: integer
                  minimum: 30
                  maximum: 315360000
                  description: Use this parameter to override the JWT lifetime.
                  nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - token
                  jwt:
                    type: string
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /v1/client/sessions:
    delete:
      summary: Remove Client's Sessions
      description: Removes all the sessions of the current client without removing the __client cookie
      tags:
      - Sessions
      operationId: removeClientSessionsAndRetainCookie
      responses:
        '200':
          $ref: '#/components/responses/Client.DeleteSession'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}:
    get:
      operationId: getSession
      summary: Get Session
      description: Returns the session with the given id
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      responses:
        '200':
          $ref: '#/components/responses/Client.Session'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/touch:
    post:
      operationId: touchSession
      summary: Touch Session
      description: 'Specify the active session for the client.


        When force organization selection is enabled and `active_organization_id` is sent as null or empty string,

        the session will keep the previous active organization and will not attempt to switch to a personal account.'
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                active_organization_id:
                  type: string
                  description: 'The ID or slug of the organization to activate.


                    When force organization selection is enabled and this value is sent as null or empty string,

                    the session will keep the previous active organization and will not attempt to switch to a personal account.'
                  nullable: true
                intent:
                  type: string
                  description: Indicates why the touch request was triggered.
                  enum:
                  - focus
                  - select_session
                  - select_org
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.TouchSession'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/end:
    post:
      operationId: endSession
      summary: End Session
      description: Marks the given session as ended.
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      responses:
        '200':
          $ref: '#/components/responses/Client.Session'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/remove:
    post:
      operationId: removeSession
      summary: Remove Session
      description: Delete the given session.
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      responses:
        '200':
          $ref: '#/components/responses/Client.Session'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/tokens:
    post:
      summary: Create Session Token
      description: 'Create a session JWT for the authenticated requested user.


        When force organization selection is enabled and `organization_id` is sent as null or empty string,

        the token will be created with the previous active organization and will not attempt to switch to a personal account.'
      operationId: createSessionToken
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                organization_id:
                  type: string
                  description: 'The organization ID to associate with the token. The user must be a member of the organization.

                    If present but empty, the personal account will be set as active.

                    If absent, the previous active organization for the session will be used.


                    When force organization selection is enabled and this value is sent as null or empty string,

                    the token will be created with the previous active organization and will not attempt to switch to a personal account.'
                  nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  jwt:
                    type: string
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/tokens/{template_name}:
    post:
      summary: Create Session Token with JWT Template
      description: Create a session JWT for the authenticated requested user.
      operationId: createSessionTokenWithTemplate
      tags:
      - Sessions
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: The user session ID.
      - in: path
        name: template_name
        required: true
        schema:
          type: string
        description: the template name
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  jwt:
                    type: string
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/verify:
    post:
      summary: Start a New Session Reverification
      description: 'Start a new session reverification flow by providing a verification level.


        If the requested level equals ''secondFactor'' or ''multiFactor'' and the associated user

        doesn''t have any available second factor, then we fall back to ''firstFactor'''
      tags:
      - Sessions
      operationId: startSessionReverification
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: the user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                level:
                  type: string
                  description: The level of authentication that the user needs to go through
                  enum:
                  - first_factor
                  - second_factor
                  - multi_factor
              required:
              - level
      responses:
        '200':
          $ref: '#/components/responses/Client.SessionReverification'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/verify/prepare_first_factor:
    post:
      summary: Prepare Session Reverification First Factor
      description: 'Prepare the first factor verification.

        Depending on the strategy, this request will do something different.


        Parameter actions:

        If the strategy equals email_code then this request will send an email with an OTP code.

        If the strategy equals phone_code then this request will send an SMS with an OTP code.'
      tags:
      - Sessions
      operationId: prepareSessionReverificationFirstFactor
      parameters:
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: the user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                strategy:
                  type: string
                  description: The strategy to be prepared for first factor authentication.
                  enum:
                  - email_code
                  - phone_code
                  - passkey
                  - enterprise_sso
                email_address_id:
                  type: string
                  description: Used with the `email_code` strategy.
                  nullable: true
                phone_number_id:
                  type: string
                  description: Used with the `phone_code` strategy.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SessionReverification'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/verify/attempt_first_factor:
    post:
      summary: Attempt Session Reverification First Factor
      description: 'Attempt the first factor verification.

        Requires the first factor verification to be prepared, unless you''re using a password.


        Parameter rules:

        If the strategy equals `email_code` then a code is required.

        If the strategy equals `password` then a password is required.'
      tags:
      - Sessions
      operationId: attemptSessionReverificationFirstFactor
      parameters:
      - in: header
        name: Origin
        description: The origin of the request
        schema:
          type: string
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: the user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                strategy:
                  type: string
                  description: The strategy to be used for first factor authentication.
                  enum:
                  - email_code
                  - password
                  - phone_code
                  - passkey
                code:
                  type: string
                  description: The code that was sent to the email. Used with the `email_code` and `phone_code` strategies.
                  nullable: true
                password:
                  type: string
                  description: Used with the `password` strategy.
                  nullable: true
                public_key_credential:
                  type: string
                  description: Used with the `passkey` strategy.
                  nullable: true
              required:
              - strategy
      responses:
        '200':
          $ref: '#/components/responses/Client.SessionReverification'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/verify/prepare_second_factor:
    post:
      summary: Prepare Session Reverification Second Factor
      description: 'Prepare the second factor verification.

        Requires the `status` to be equal to `needs_second_factor`.'
      tags:
      - Sessions
      operationId: prepareSessionReverificationSecondFactor
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: the user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                strategy:
                  type: string
                  description: The strategy to be prepared for second factor authentication.
                  nullable: true
                  enum:
                  - phone_code
                phone_number_id:
                  type: string
                  description: Used with the `phone_code` strategy.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Client.SessionReverification'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/client/sessions/{session_id}/verify/attempt_second_factor:
    post:
      summary: Attempt Session Reverification Second Factor
      description: 'Attempt the second factor verification.

        Requires the `status` to be equal to `needs_second_factor` and for the preparation step to have been called.'
      tags:
      - Sessions
      operationId: attemptSessionReverificationSecondFactor
      parameters:
      - in: path
        name: session_id
        required: true
        schema:
          type: string
        description: the user session ID.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                strategy:
                  type: string
                  description: The strategy to be attempted for second factor authentication.
                  enum:
                  - phone_code
                  - totp
                  - backup_code
                code:
                  type: string
                  description: Used with the `phone_code`, `totp` and `backup_code` strategies.
      responses:
        '200':
          $ref: '#/components/responses/Client.SessionReverification'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
components:
  schemas:
    Token_2:
      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.GoogleOneTap:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_google_one_tap
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - google_one_tap
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    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
          - replaced
          - pending
        last_active_organization_id:
          type: string
          nullable: true
        last_active_at:
          type: integer
        latest_activity:
          $ref: '#/components/schemas/SessionActivityResponse'
        expire_at:
          type: integer
          format: int64
          description: 'Unix timestamp of expiration.

            '
        abandon_at:
          type: integer
          format: int64
          description: 'Unix timestamp of abandonment.

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

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

            '
        tasks:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SessionTask'
      required:
      - object
      - id
      - user_id
      - client_id
      - status
      - last_active_at
      - expire_at
      - abandon_at
      - updated_at
      - created_at
    SessionTask:
      type: object
      properties:
        key:
          type: string
      required:
      - key
    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 JSON Web Token (JWT) value.

            '
      required:
      - object
      - jwt
    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:
          nullable: true
          type: string
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type: object
            nullable: true
        expire_at:
          type: integer
          nullable: true
        attempts:
          type: integer
          nullable: true
      required:
      - status
      - strategy
    Client.PublicUserData:
      type: object
      additionalProperties: false
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        image_url:
          type: string
          nullable: true
        has_image:
          type: boolean
        identifier:
          type: string
        profile_image_url:
          type: string
          nullable: true
          deprecated: true
          description: Use `image_url` instead.
        user_id:
          type: string
          nullable: true
        username:
          type: string
          nullable: true
        banned:
          type: boolean
      required:
      - first_name
      - last_name
      - identifier
      - has_image
    Client.SessionReverification:
      type: object
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - session_reverification
        level:
          type: string
          description: The level used for the session reverification
        status:
          type: string
          enum:
          - needs_first_factor
          - needs_second_factor
          - complete
        supported_first_factors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
        supported_second_factors:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/Stubs.SignInFactor'
     

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