> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify a session token and resolve its organization

> Takes the app-scoped token the App Bridge handed your iframe and returns the Max AI organization it belongs to, but only if your app has an ACTIVE installation for that organization. Use this instead of trusting `X-Organization-Id`, which is iframe metadata rather than proof, and instead of verifying the JWT yourself — the ways to get that subtly wrong (trusting the token's own `iss`, accepting `alg: none`) are authentication bypasses. Returns 401 for an invalid token, a token with no active organization, or an organization your app is not installed for; the three are deliberately not distinguished in the response.



## OpenAPI

````yaml /openapi-v4.json post /marketplace/verify-session
openapi: 3.0.0
info:
  title: Max AI Public API
  description: API for third-party marketplace apps
  version: '4.0'
  contact: {}
servers:
  - url: https://api.maxcare.ai/v4
security: []
tags: []
paths:
  /marketplace/verify-session:
    post:
      tags:
        - Marketplace
      summary: Verify a session token and resolve its organization
      description: >-
        Takes the app-scoped token the App Bridge handed your iframe and returns
        the Max AI organization it belongs to, but only if your app has an
        ACTIVE installation for that organization. Use this instead of trusting
        `X-Organization-Id`, which is iframe metadata rather than proof, and
        instead of verifying the JWT yourself — the ways to get that subtly
        wrong (trusting the token's own `iss`, accepting `alg: none`) are
        authentication bypasses. Returns 401 for an invalid token, a token with
        no active organization, or an organization your app is not installed
        for; the three are deliberately not distinguished in the response.
      operationId: MarketplacePublicController_verifySession
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifySessionBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifySessionSuccessResponseV3'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUnauthorizedResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiRateLimitResponse'
      security:
        - api-key: []
components:
  schemas:
    VerifySessionBody:
      type: object
      properties:
        sessionToken:
          type: string
          description: >-
            The app-scoped token the App Bridge handed your iframe —
            `maxcare.appToken()`, or the `auth:token-request` reply. Named
            `sessionToken` for wire compatibility; a Clerk session token is not
            accepted here, and the platform no longer issues one to embedded
            apps.
          example: >-
            eyJhbGciOiJFUzI1NiIsImtpZCI6InlQOVBQb095dURFNnVKVXNYYlo3TmZKck41M21xM1I1blJtTFBEdk4zWlUifQ...
      required:
        - sessionToken
    VerifySessionSuccessResponseV3:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: success
        data:
          $ref: '#/components/schemas/VerifySessionDataResponseV3'
      required:
        - code
        - data
    PublicApiUnauthorizedResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: unauthorized
        message:
          type: string
          description: Human-readable error message
          example: Invalid or missing API key
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiRateLimitResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message
          example: Rate limit exceeded. Maximum 1000 requests per 60 seconds.
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    VerifySessionDataResponseV3:
      type: object
      properties:
        organizationId:
          type: string
          description: >-
            Max AI organization the session belongs to. Use this as your tenant
            key. Matches the `organization.id` returned by `GET /marketplace/me`
            on this version.
          example: org_a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d
        clerkOrganizationId:
          type: string
          description: The organization's Clerk id
          example: org_38dgm0BKetZbaGtOlbsPxr2HheD
        clerkUserId:
          type: string
          description: >-
            Clerk user the token was issued for. A CLERK id, so it keeps Clerk's
            `user_` prefix on every version and is never rewritten to the `usr_`
            readable form. Not the token's `sub` verbatim — that claim is a Max
            AI user uuid, which this API translates.
          example: user_36uZihkXH7t0iB5RWRTbhPh1N2W
        installationId:
          type: string
          description: >-
            Your installation for this organization. Present only when the
            installation is active. Opaque and unprefixed on every version — it
            is a handle to echo back, not a key you join other resources on.
          example: b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e
      required:
        - organizationId
        - clerkOrganizationId
        - clerkUserId
        - installationId
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Marketplace API key

````