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

# Exchange an identity assertion for a member token

> Obtain a short-lived token that acts as one member of the organization, for an approved app.

Form-encoded per RFC 8693 §2.1. The app sends its own machine access token as the actor and
a signed identity assertion naming the member as the subject. The organization's admin must
have approved the app's client in Settings, and the member must not have opted out of the
app. The token lives 15 minutes, is read-only, carries at most the approval's scopes, and is
re-checked against the approval and the member's choice on use.

Errors use the OAuth token-endpoint shape (``error``, ``error_description``): 400
``invalid_request`` / ``unsupported_grant_type`` / ``invalid_grant``, 403 ``access_denied``
with the reason, 503 ``temporarily_unavailable``.



## OpenAPI

````yaml https://api.summation.com/openapi.json post /v1/auth/token-exchange
openapi: 3.1.0
info:
  title: summation-api public API
  version: 0.1.0
servers: []
security: []
tags:
  - name: Auth
    description: Machine authentication for API clients.
  - name: Tenant
    description: Organization and tenant context resolved by summation-api.
  - name: Projects
    description: Project resources.
  - name: Conversations
    description: Conversation and message resources.
  - name: Reports
    description: Report resources and report operations.
  - name: Runs
    description: Project run history and execution status.
  - name: Playbooks
    description: Playbook resources.
  - name: Files
    description: Project file resources.
  - name: Catalog Entries
    description: Project-scoped data asset attachments.
  - name: Data Connectors
    description: Reusable external data source connections.
  - name: App Connectors
    description: External app connectors whose tools the agent can use during chat.
  - name: Tables
    description: Canonical table metadata and catalog.
  - name: Views
    description: Canonical Summation view metadata and catalog.
  - name: Query Executions
    description: Read-only SQL query execution.
  - name: Grid
    description: Materialized grid status, sync, and lineage.
  - name: Schedules
    description: Schedule and schedule run inspection.
  - name: Workflows
    description: >-
      Workflows: what they run, when they run, and where their output is
      delivered.
  - name: Verification Tests
    description: >-
      Administrative custom verification-test definitions, overlays, and
      effective-set previews.
paths:
  /v1/auth/token-exchange:
    post:
      tags:
        - Auth
      summary: Exchange an identity assertion for a member token
      description: >-
        Obtain a short-lived token that acts as one member of the organization,
        for an approved app.


        Form-encoded per RFC 8693 §2.1. The app sends its own machine access
        token as the actor and

        a signed identity assertion naming the member as the subject. The
        organization's admin must

        have approved the app's client in Settings, and the member must not have
        opted out of the

        app. The token lives 15 minutes, is read-only, carries at most the
        approval's scopes, and is

        re-checked against the approval and the member's choice on use.


        Errors use the OAuth token-endpoint shape (``error``,
        ``error_description``): 400

        ``invalid_request`` / ``unsupported_grant_type`` / ``invalid_grant``,
        403 ``access_denied``

        with the reason, 503 ``temporarily_unavailable``.
      operationId: exchange_token
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_exchange_token'
      responses:
        '200':
          description: A read-only token acting as the member was issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeResponse'
        '400':
          description: >-
            invalid_request (malformed or missing fields, unsupported token
            types), unsupported_grant_type, or invalid_grant (the assertion or
            the actor token does not verify).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeError'
        '403':
          description: >-
            access_denied: the client is not approved, the approval was revoked,
            the member opted out or is not an active member, background calls
            are not allowed, or a requested scope is outside the approval's
            ceiling. error_description names the reason.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '502':
          description: >-
            server_error: the exchange failed for a reason that is not a
            refusal. Retry shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeError'
        '503':
          description: 'temporarily_unavailable: retry shortly.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenExchangeError'
components:
  schemas:
    Body_exchange_token:
      properties:
        grant_type:
          type: string
          title: Grant Type
          description: Must be urn:ietf:params:oauth:grant-type:token-exchange.
          default: ''
        subject_token:
          type: string
          title: Subject Token
          description: >-
            The identity assertion naming the member: a signed JWT from an
            issuer the organization's admin trusts, carrying iss, aud, sub (the
            member's email), name, presence ('session' or 'none'), jti and exp.
          default: ''
        subject_token_type:
          type: string
          title: Subject Token Type
          description: Must be urn:ietf:params:oauth:token-type:jwt.
          default: ''
        actor_token:
          type: string
          title: Actor Token
          description: >-
            The app's own machine access token, as issued by the machine token
            endpoint. May instead be sent as Authorization: Bearer <token>; use
            one of the two, never both.
          default: ''
        actor_token_type:
          type: string
          title: Actor Token Type
          description: >-
            Must be urn:ietf:params:oauth:token-type:access_token when
            actor_token is sent in the form.
          default: ''
        scope:
          type: string
          title: Scope
          description: >-
            Optional space-delimited scopes for the member token. Leave empty
            for everything the approval allows; any scope outside the approval's
            ceiling is refused with access_denied, never dropped.
          default: ''
      type: object
      title: Body_exchange_token
    TokenExchangeResponse:
      properties:
        access_token:
          type: string
          title: Access Token
          description: >-
            Bearer token that acts as the member named by the identity
            assertion. Send it unchanged as Authorization: Bearer <token>. It is
            read-only and expires after expires_in seconds.
        issued_token_type:
          type: string
          title: Issued Token Type
          description: Always urn:ietf:params:oauth:token-type:access_token.
        token_type:
          type: string
          title: Token Type
          description: 'Token type for the Authorization header: ''Bearer''.'
          default: Bearer
        expires_in:
          type: integer
          title: Expires In
          description: Token lifetime in seconds; exchange again shortly before expiry.
        scope:
          type: string
          title: Scope
          description: >-
            Space-delimited scopes the token carries (never more than the
            approval allows).
      type: object
      required:
        - access_token
        - issued_token_type
        - expires_in
        - scope
      title: TokenExchangeResponse
      description: >-
        OAuth2 token-exchange response (RFC 8693 §2.2.1): a short-lived token
        that acts as one member.
    TokenExchangeError:
      properties:
        error:
          type: string
          title: Error
          description: >-
            Stable error code: invalid_request, unsupported_grant_type,
            invalid_grant, access_denied, temporarily_unavailable, or
            server_error.
        error_description:
          type: string
          title: Error Description
          description: Human-readable reason, safe to show to an operator.
      type: object
      required:
        - error
        - error_description
      title: TokenExchangeError
      description: >-
        OAuth2 token-endpoint error (RFC 6749 §5.2). Not the problem+json
        envelope: OAuth clients parse this shape.
    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

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.