cQnce

cQnce Auth – Agent API

Agent OTP-based registration and login

Documentation GitHub OpenAPI

Operations 16

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/cqnce-app:cqnce-app-auth-agent-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: cQnce Auth – Agent API
  description: 'Authorization-request routing and agent-management API for the cQnce platform.


    ## Authentication


    | Scheme | Header | Used by |

    |---|---|---|

    | Bearer JWT (tenant) | `Authorization: Bearer ` | Dashboard / admin routes |

    | Bearer JWT (agent) | `Authorization: Bearer ` | Agent mobile app routes |

    | API Key | `x-api-key: ` | Server-to-server request submission |'
  version: 1.0.0
  contact:
    name: cQnce Support
servers:
- url: https://api.cqnce.app
  description: Production
tags:
- name: Auth – Agent
  description: Agent OTP-based registration and login
paths:
  /v1/auth/agent/send-otp:
    post:
      tags:
      - Auth – Agent
      summary: Send OTP
      description: Sends a one-time password to the provided phone number. Rate-limited to 5 requests per 15 minutes per IP.
      operationId: agentSendOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone
              properties:
                phone:
                  type: string
                  example: '+15551234567'
      responses:
        '200':
          description: OTP sent (non-production environments also return the code in the response)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OTP sent
                  code:
                    type: string
                    description: Only present outside production
                    example: '123456'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/verify-otp:
    post:
      tags:
      - Auth – Agent
      summary: Verify OTP
      description: Verifies the OTP code and returns a short-lived `verifyToken` (60 min) used to complete agent registration or login.
      operationId: agentVerifyOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone
              - code
              properties:
                phone:
                  type: string
                  example: '+15551234567'
                code:
                  type: string
                  example: '123456'
      responses:
        '200':
          description: OTP verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  verifyToken:
                    type: string
                    description: Short-lived JWT (60 min)
                  isRegistered:
                    type: boolean
                    description: Whether the phone number already has a registered agent account (useful for reinstall detection on the mobile app)
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or expired OTP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/send-email-otp:
    post:
      tags:
      - Auth – Agent
      summary: Send Email OTP
      description: Sends a one-time password to the provided email address. Rate-limited to 5 requests per 15 minutes per IP.
      operationId: agentSendEmailOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  example: jane@example.com
      responses:
        '200':
          description: OTP sent (non-production environments also return the code in the response)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OTP sent
                  code:
                    type: string
                    description: Only present outside production
                    example: '123456'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/verify-email-otp:
    post:
      tags:
      - Auth – Agent
      summary: Verify Email OTP
      description: Verifies the OTP code sent to an email address and returns a short-lived `emailVerifyToken` (60 min) used to confirm email ownership during registration.
      operationId: agentVerifyEmailOtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - code
              properties:
                email:
                  type: string
                  format: email
                  example: jane@example.com
                code:
                  type: string
                  example: '123456'
      responses:
        '200':
          description: Email OTP verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  emailVerifyToken:
                    type: string
                    description: Short-lived JWT (60 min)
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or expired OTP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/register:
    post:
      tags:
      - Auth – Agent
      summary: Register agent
      description: Creates a new agent account. Requires a valid `verifyToken` from the OTP flow.
      operationId: agentRegister
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone
              - name
              - verifyToken
              properties:
                phone:
                  type: string
                  example: '+15551234567'
                name:
                  type: string
                  example: Jane
                surname:
                  type: string
                  example: Doe
                email:
                  type: string
                  format: email
                  example: jane@example.com
                verifyToken:
                  type: string
                emailVerifyToken:
                  type: string
                  description: Short-lived JWT from the email OTP flow. Required when email is provided.
      responses:
        '201':
          description: Agent registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Agent JWT (30 days)
                  agent:
                    $ref: '#/components/schemas/Agent'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid verifyToken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/login:
    post:
      tags:
      - Auth – Agent
      summary: Agent login
      description: Authenticates an existing agent and returns a 30-day JWT. Requires a valid `verifyToken`.
      operationId: agentLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone
              - verifyToken
              properties:
                phone:
                  type: string
                  example: '+15551234567'
                verifyToken:
                  type: string
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Agent JWT (30 days)
                  refreshToken:
                    type: string
                    description: Rotating refresh token
                  agent:
                    $ref: '#/components/schemas/Agent'
                  deviceId:
                    type: string
                    format: uuid
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid verifyToken or phone not registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/refresh:
    post:
      tags:
      - Auth – Agent
      summary: Refresh agent token
      description: Exchanges a valid refresh token for a new access token and refresh token pair (token rotation).
      operationId: agentRefreshToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - refreshToken
              properties:
                refreshToken:
                  type: string
                  description: The refresh token from a previous login or refresh
      responses:
        '200':
          description: New token pair issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: New agent JWT
                  refreshToken:
                    type: string
                    description: New rotating refresh token
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid, revoked, or expired refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/logout:
    post:
      tags:
      - Auth – Agent
      summary: Agent logout
      description: Marks the agent as offline and revokes all refresh tokens for their device.
      operationId: agentLogout
      security:
      - agentJWT: []
      responses:
        '200':
          description: Logged out successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-link/init:
    post:
      tags:
      - Auth – Agent
      summary: Initialise QR web-link token
      description: Generates a short-lived (2-minute) link token to be encoded as a QR code in the agent-web portal. No authentication required.
      operationId: agentWebLinkInit
      responses:
        '200':
          description: Link token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  linkToken:
                    type: string
                    description: 64-character hex token
                  expiresAt:
                    type: string
                    format: date-time
  /v1/auth/agent/web-link/confirm:
    post:
      tags:
      - Auth – Agent
      summary: Confirm QR web-link (mobile)
      description: Called by the mobile app after scanning the QR code. Links the scanned token to the authenticated agent and issues a persistent web-session JWT.
      operationId: agentWebLinkConfirm
      security:
      - agentJWT: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - linkToken
              properties:
                linkToken:
                  type: string
                  description: Token scanned from the QR code
      responses:
        '200':
          description: Web session confirmed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  webSessionToken:
                    type: string
                    description: Persistent web-session JWT
                  agent:
                    $ref: '#/components/schemas/Agent'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Link token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Link token already used
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Link token has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-link/poll/{linkToken}:
    get:
      tags:
      - Auth – Agent
      summary: Poll QR web-link status
      description: Polled by the agent-web portal to check whether the mobile app has confirmed the QR link. Returns the web-session token when confirmed.
      operationId: agentWebLinkPoll
      parameters:
      - name: linkToken
        in: path
        required: true
        schema:
          type: string
        description: The link token from /web-link/init
      responses:
        '200':
          description: Link status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - pending
                    - confirmed
                    - expired
                    - revoked
                    - not_found
                  webSessionToken:
                    type: string
                    description: Present only when status=confirmed
                  agent:
                    $ref: '#/components/schemas/Agent'
                    description: Present only when status=confirmed
        '404':
          description: Link token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-link/promote:
    post:
      tags:
      - Auth – Agent
      summary: Promote OTP session to web session
      description: Exchanges a short-lived OTP access token for a persistent web-session JWT backed by an `AgentWebSession` DB record. Allows the agent-web portal to obtain a durable session without going through the QR flow.
      operationId: agentWebLinkPromote
      security:
      - agentJWT: []
      responses:
        '200':
          description: Web session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  webSessionToken:
                    type: string
                    description: Persistent web-session JWT (no expiry)
                  agent:
                    $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Already authenticated with a web session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-login:
    post:
      tags:
      - Auth – Agent
      summary: Agent web-portal login
      description: Preferred login path for the agent-web portal. Exchanges a verified OTP (`verifyToken`) directly for a persistent web-session JWT without creating a mobile-style access/refresh token pair.
      operationId: agentWebLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - phone
              - verifyToken
              properties:
                phone:
                  type: string
                  example: '+15551234567'
                verifyToken:
                  type: string
                  description: Verify token from the OTP verification step
      responses:
        '200':
          description: Web session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  webSessionToken:
                    type: string
                    description: Persistent web-session JWT
                  agent:
                    $ref: '#/components/schemas/Agent'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid verifyToken or phone not registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-sessions:
    get:
      tags:
      - Auth – Agent
      summary: List active web sessions
      description: Returns all active (non-revoked) web sessions for the authenticated agent. Used by the mobile app to manage linked browser sessions.
      operationId: listAgentWebSessions
      security:
      - agentJWT: []
      responses:
        '200':
          description: List of active web sessions
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        deviceId:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        userAgent:
                          type:
                          - string
                          - 'null'
                        lastSeenAt:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        createdAt:
                          type: string
                          format: date-time
                        linkTokenId:
                          type:
                          - string
                          - 'null'
                          format: uuid
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/web-sessions/{sessionId}:
    delete:
      tags:
      - Auth – Agent
      summary: Revoke web session
      description: Revokes an active web session. The linked browser tab will be logged out on its next request.
      operationId: revokeAgentWebSession
      security:
      - agentJWT: []
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Web session ID
      responses:
        '200':
          description: Web session revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Web session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Web session already revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/auth/agent/widget-sso:
    post:
      tags:
      - Auth – Agent
      summary: Widget SSO token exchange
      description: Exchanges an integrator-signed SSO token for a widget session JWT. Used by embedded widgets to authenticate end-users without exposing the signing secret to the browser.
      operationId: agentWidgetSso
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - integrationKey
              - ssoToken
              - origin
              properties:
                integrationKey:
                  type: string
                  description: The `wik_*` integration key for the widget
                ssoToken:
                  type: string
                  description: JWT signed with the integration signing secret
                origin:
                  type: string
                  description: The origin of the requesting page (must be in allowedOrigins)
      responses:
        '200':
          description: Widget session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  widgetSessionToken:
                    type: string
                    description: Widget session JWT
        '400':
          description: Validation error or invalid SSO token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Origin not allowed or integration inactive
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Integration not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          example: Validation failed
        details:
          type: array
          items:
            type: object
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        surname:
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
          format: email
        phone:
          type: string
        online:
          type: boolean
        tenantId:
          type:
          - string
          - 'null'
          format: uuid
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    tenantJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued on tenant login (`POST /v1/auth/login`)
    agentJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued on agent login/register (`POST /v1/auth/agent/login` or `/register`)
    projectApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Per-project API key used for server-to-server request submission