Clerk Sign-in Tokens API

openapi: 3.2.0
info:
  title: Clerk Backend Sign-in Tokens 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.


    Please see https://clerk.com/docs for more information.'
  version: '2026-08-20'
  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: 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.'
paths:
  /sign_in_tokens:
    post:
      summary: Create sign-in token
      x-speakeasy-group: signInTokens
      x-speakeasy-name-override: create
      description: 'Creates a new sign-in token and associates it with the given user.

        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
                org_id:
                  type:
                  - string
                  - 'null'
                  description: 'The ID of the organization to activate when the user signs in.

                    Organizations must be enabled for the instance, and the user must be a member of the organization.'
                expires_in_seconds:
                  type:
                  - integer
                  - 'null'
                  description: 'Optional parameter to specify the life duration of the sign in token in seconds.

                    By default, the duration is 30 days, or 10 minutes when `second_factor_verification` is set.'
                  minimum: 1
                second_factor_verification:
                  type:
                  - string
                  - 'null'
                  enum:
                  - fresh
                  - stale
                  - null
                  description: 'Optional parameter that lets a user with a second factor enabled complete the sign in without being prompted for it.

                    When omitted, redeeming the token completes only the first factor, and the user must still complete their second factor.

                    `fresh`: the second factor is treated as verified at sign in. The session token''s `fva` claim reports a second factor age of 0.

                    `stale`: the second factor is treated as unverified. The session token''s `fva` claim reports the maximum second factor age of 99999, so any reverification that requires a second factor prompts the user to complete one.

                    Has no effect for users without a second factor enabled.

                    A token created with this parameter signs in a user with a second factor enabled without prompting for it, so `expires_in_seconds` defaults to 10 minutes. We recommend keeping it short.'
              required:
              - user_id
      responses:
        '200':
          $ref: '#/components/responses/SignInToken'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /sign_in_tokens/{sign_in_token_id}/revoke:
    post:
      operationId: RevokeSignInToken
      x-speakeasy-group: signInTokens
      x-speakeasy-name-override: revoke
      summary: Revoke the given sign-in token
      description: Revokes a pending sign-in token
      tags:
      - Sign-in Tokens
      parameters:
      - name: sign_in_token_id
        in: path
        description: The ID of the sign-in token to be revoked
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/SignInToken'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
components:
  schemas:
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
          additionalProperties: true
        clerk_trace_id:
          type: string
      required:
      - errors
    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
          - 'null'
        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
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
          additionalProperties: true
      required:
      - message
      - long_message
      - code
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    SignInToken:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SignInToken'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true