openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Embed tokens
  version: 1.0.0
  description: |
    Mint a short-lived token admitting one respondent to one assessment, inside
    one website (the "controlled" embed tier).

    CALL THIS FROM YOUR BACKEND, NEVER FROM A BROWSER. It requires a service
    token, which would be public the moment it appeared in page source, and the
    point of this tier is that a trusted party vouches for the respondent.

    A token NARROWS what may frame the assessment; it can never widen it. The
    campaign's registered-origins list still applies and the effective policy is
    the intersection, so:

      * a valid token restricts framing to the single origin it names, even when
        the campaign has several registered — which is how you stop one client's
        page showing an assessment issued for another's;
      * an invalid or expired token grants nothing: framing simply falls back to
        the campaign's own allowlist;
      * a token naming an origin the campaign has not registered results in no
        framing at all.

    The origin must ALREADY be registered under the campaign's Embedding
    settings before a token can be minted for it (409 otherwise). Minting one
    for an unregistered origin would sign a promise the framing policy then
    refuses to keep, leaving the integrator with a valid token and a blank
    rectangle.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicEmbedTokens
paths:
  /api/v2/public/accounts/{accountId}/embed-tokens:
    post:
      tags: [PublicEmbedTokens]
      operationId: v2MintEmbedToken
      summary: Mint an embed token for one assessment on one origin.
      description: |
        Scope embed:issue. Mint immediately before rendering the iframe — the
        default life is 15 minutes and the maximum is 60, because these are
        issued per page render and a longer life only widens the replay window.

        Pass the returned token to the embed snippet as `data-token`.

        Responses are `Cache-Control: no-store`: the token is a bearer
        credential.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MintEmbedTokenRequest'
      responses:
        '200':
          description: Token minted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MintEmbedTokenResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404':
          description: |
            The campaign is not this account's, or the assessment does not
            exist, is not Active, or belongs to a different campaign. All of
            these return the SAME body deliberately, so a token holder cannot
            enumerate assessment keys by comparing responses.
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelope'
        '409':
          description: |
            The origin is not registered for this campaign. Add it under the
            campaign's Embedding settings first.
          content:
            application/json:
              schema:
                $ref: '../../v1/components/envelopes.yaml#/components/schemas/ErrorEnvelope'
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      type: http
      scheme: bearer
      description: Service token holding the embed:issue scope, scoped to accountId.
  schemas:
    MintEmbedTokenRequest:
      type: object
      required: [campaignId, assessmentKey, origin]
      additionalProperties: false
      properties:
        campaignId:
          type: string
          description: Campaign the assessment belongs to. Must be this account's.
        assessmentKey:
          type: string
          description: |
            The assessment's public key. Case-insensitive; stored uppercased in
            the token.
        origin:
          type: string
          description: |
            The single website allowed to frame the assessment with this token —
            scheme and host only, no path and no wildcard (e.g.
            https://www.example.com). Must already be registered for the
            campaign. http is accepted only for localhost.
          examples: ['https://www.example.com']
        email:
          type: string
          format: email
          description: |
            Optional. Identifies the respondent, so their submission attaches to
            the matching participant instead of creating an anonymous one.
            Lower-cased when signed.
        ttlSeconds:
          type: integer
          minimum: 1
          maximum: 3600
          default: 900
          description: Token life. Values above the maximum are capped, not rejected.
    MintEmbedTokenResponse:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, const: true }
        data:
          type: object
          required: [token, expiresAt, jti, maxTtlSeconds]
          properties:
            token:
              type: string
              description: |
                The signed token. Treat as a bearer credential: hand it straight
                to the embed snippet and do not log or store it.
            expiresAt:
              type: integer
              description: Expiry, epoch milliseconds.
            jti:
              type: string
              description: |
                Unique id for this mint. Recorded so a submission can be traced
                back to the issuing call without holding the token itself.
            maxTtlSeconds:
              type: integer
              description: The server's ceiling, echoed so a caller can see when its ttlSeconds was capped.
