ctlsurf

ctlsurf Auth API

The auth API from ctlsurf — 13 operation(s) for auth.

Documentation GitHub OpenAPI

Operations 13

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/ctlsurf-com:ctlsurf-com-auth-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Ctlsurf Com Auth API
  version: 0.1.0
  description: 'Operations tagged auth across 2 of this provider''s published API definitions: ctlsurf-com-openapi.json, ctlsurf-com-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.ctlsurf.com
  description: ctlsurf application host (documented MCP endpoint https://app.ctlsurf.com/api/mcp; spec served at /openapi.json)
tags:
- name: Auth
paths:
  /api/auth/register:
    post:
      tags:
      - Auth
      summary: Register
      description: Register a new user account.
      operationId: register_api_auth_register_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/login:
    post:
      tags:
      - Auth
      summary: Login
      description: Login with email and password.
      operationId: login_api_auth_login_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLogin'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh Token
      description: Get new access token using refresh token.
      operationId: refresh_token_api_auth_refresh_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/me:
    get:
      tags:
      - Auth
      summary: Get Current User Info
      description: Get current authenticated user's information.
      operationId: get_current_user_info_api_auth_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
      security:
      - HTTPBearer: []
  /api/auth/chat-logging:
    put:
      tags:
      - Auth
      summary: Toggle Chat Logging
      description: Toggle global chat logging for the current user.
      operationId: toggle_chat_logging_api_auth_chat_logging_put
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Body
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/auth/logout:
    post:
      tags:
      - Auth
      summary: Logout
      description: 'Logout endpoint.

        Note: JWT tokens are stateless, so this is a client-side operation.

        The client should discard the tokens.'
      operationId: logout_api_auth_logout_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/auth/request-password-change-otp:
    post:
      tags:
      - Auth
      summary: Request Password Change Otp
      description: Request OTP for password change. Sends a 6-digit code to user's email.
      operationId: request_password_change_otp_api_auth_request_password_change_otp_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeOTPRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/auth/change-password:
    post:
      tags:
      - Auth
      summary: Change Password
      description: Change current user's password with OTP verification.
      operationId: change_password_api_auth_change_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordChangeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/auth/verify-email:
    post:
      tags:
      - Auth
      summary: Verify Email
      description: Verify user's email address using token from email.
      operationId: verify_email_api_auth_verify_email_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/resend-verification:
    post:
      tags:
      - Auth
      summary: Resend Verification
      description: Resend verification email.
      operationId: resend_verification_api_auth_resend_verification_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendVerificationRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/forgot-password:
    post:
      tags:
      - Auth
      summary: Forgot Password
      description: Request password reset email.
      operationId: forgot_password_api_auth_forgot_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForgotPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/reset-password:
    post:
      tags:
      - Auth
      summary: Reset Password
      description: Reset password using token from email.
      operationId: reset_password_api_auth_reset_password_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/auth/pair-device:
    post:
      tags:
      - Auth
      summary: Pair Device
      description: 'Issue an API key for a desktop app that redirected the user here.


        The desktop app starts a localhost HTTP server, then opens the browser to

        ctlsurf''s /pair-device page. After the user approves, the frontend POSTs

        here and redirects the browser to redirect_uri?key=...


        First-party desktop apps get an app key (cak_): one credential for notebook/MCP

        access AND the managed Supporting Services, bound to the user''s Business org.

        kind="sidekick" requires a Business org (transcription + LLM). kind="worker"

        (ctlsurf Worker) gets a cak_ for managed voice transcription when the user has

        one, otherwise a regular cpk_. Any other kind mints a regular cpk_ MCP key.'
      operationId: pair_device_api_auth_pair_device_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PairDeviceRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    PasswordChangeOTPRequest:
      properties:
        current_password:
          type: string
          title: Current Password
      type: object
      required:
      - current_password
      title: PasswordChangeOTPRequest
      description: Schema for requesting password change OTP.
    ResetPasswordRequest:
      properties:
        token:
          type: string
          title: Token
        new_password:
          type: string
          title: New Password
      type: object
      required:
      - token
      - new_password
      title: ResetPasswordRequest
      description: Schema for password reset with token.
    ForgotPasswordRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ForgotPasswordRequest
      description: Schema for forgot password request.
    ResendVerificationRequest:
      properties:
        email:
          type: string
          format: email
          title: Email
      type: object
      required:
      - email
      title: ResendVerificationRequest
      description: Schema for resending verification email.
    PasswordChangeRequest:
      properties:
        current_password:
          type: string
          title: Current Password
        new_password:
          type: string
          title: New Password
        otp:
          type: string
          title: Otp
      type: object
      required:
      - current_password
      - new_password
      - otp
      title: PasswordChangeRequest
      description: Schema for password change request with OTP verification.
    TokenResponse:
      properties:
        access_token:
          type: string
          title: Access Token
        refresh_token:
          type: string
          title: Refresh Token
        token_type:
          type: string
          title: Token Type
          default: bearer
        user:
          $ref: '#/components/schemas/UserResponse'
      type: object
      required:
      - access_token
      - refresh_token
      - user
      title: TokenResponse
      description: Schema for token response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UserCreate:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
      type: object
      required:
      - email
      - password
      title: UserCreate
      description: Schema for user registration.
    PairDeviceRequest:
      properties:
        name:
          type: string
          title: Name
        redirect_uri:
          type: string
          title: Redirect Uri
        kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Kind
      type: object
      required:
      - name
      - redirect_uri
      title: PairDeviceRequest
    RefreshTokenRequest:
      properties:
        refresh_token:
          type: string
          title: Refresh Token
      type: object
      required:
      - refresh_token
      title: RefreshTokenRequest
      description: Schema for refresh token request.
    UserResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        email:
          type: string
          title: Email
        is_admin:
          type: boolean
          title: Is Admin
        admin_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Admin Role
        must_change_password:
          type: boolean
          title: Must Change Password
        email_verified:
          type: boolean
          title: Email Verified
        tier:
          type: string
          title: Tier
          default: free
        chat_logging_enabled:
          type: boolean
          title: Chat Logging Enabled
          default: true
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - email
      - is_admin
      - must_change_password
      - email_verified
      - created_at
      - updated_at
      title: UserResponse
      description: Schema for user response (excludes password).
    UserLogin:
      properties:
        email:
          type: string
          format: email
          title: Email
        password:
          type: string
          title: Password
      type: object
      required:
      - email
      - password
      title: UserLogin
      description: Schema for user login.
    VerifyEmailRequest:
      properties:
        token:
          type: string
          title: Token
      type: object
      required:
      - token
      title: VerifyEmailRequest
      description: Schema for email verification.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
x-refined-from:
- ctlsurf-com-openapi.json
- ctlsurf-com-openapi.yml