Eformogi Trust API

openapi: 3.2.0
info:
  title: Eformogi Trust API
  version: 33.5.1
  description: 'Eformogi is a record of learning the student owns, witnessed by the adults who were there, verifiable at one link with no login, and issued by the schools and counselors who hold the learners. The family-issued receipt (`tr_`) is a Witness Transcript. This document describes the machine-readable surface: verification, witness attestation, consent, the agent protocol, and the issuer rail (enrollment, roster, declared courses, and the family side that folds them into the transcript). The open record format itself is published at https://eformogi.com/spec.'
  contact:
    url: https://eformogi.com
  license:
    name: Proprietary
servers:
- url: https://eformogi.com
  description: Production
tags:
- name: Trust
  description: W3C Verifiable Credentials and DID
paths:
  /api/did:
    get:
      summary: DID Document (W3C did:web)
      tags:
      - Trust
      responses:
        '200':
          description: W3C DID Document for did:web:eformogi.com
          content:
            application/did+json: {}
      operationId: getApiDid
      x-operation-id-source: derived
  /api/revocation-list:
    get:
      summary: Credential revocation list
      tags:
      - Trust
      parameters:
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: type
        in: query
        schema:
          type: string
      responses:
        '200':
          description: List of revoked credential IDs
      operationId: getApiRevocationList
      x-operation-id-source: derived
  /api/verify-credential:
    post:
      summary: Verify a Verifiable Credential
      tags:
      - Trust
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credential:
                  type: object
              required:
              - credential
      responses:
        '200':
          description: Verification result with proof, issuer, revocation, expiry checks
      operationId: postApiVerifyCredential
      x-operation-id-source: derived
  /api/verify-receipt:
    get:
      summary: Verify a receipt (tr_/cr_/ws_/wn_/wl_/att_, consent or audit id)
      description: 'The single verification front door for all Eformogi receipts.

        Single-link verification is **free and keyless**. No account, no signup, ever

        (BRAND_THESIS rule 11). Paste any receipt id (`tr_`, `cr_`, `ws_`, `wn_`, `wl_`,

        `att_`, a consent receipt UUID, or an audit log id) and get back a verified,

        non-PII metadata response.


        **Optional org attribution (V31 receiver billing):** send

        `Authorization: Bearer efg_org_…` to attribute the call to your org''s plan.

        Keyed calls are counted toward your monthly verification quota

        (free orgs get 50/mo for evaluation; an office that wants a hosted

        verification service at volume can ask us at hello@eformogi.com).

        Quota state is returned in response headers:

        - `X-Verify-Quota-Plan`: your plan name (`free`, `api`, etc.)

        - `X-Verify-Quota-Limit`: monthly included verifications (omitted for unlimited plans)

        - `X-Verify-Quota-Used`: verifications used so far this calendar month


        **An invalid or unrecognised key never blocks a verify**. The endpoint falls back

        to the public (keyless) path so a misconfigured integration can never break a

        single-link verification. Orgs on a paid plan are never blocked; only free-tier

        orgs over their evaluation allowance are gated

        (and only once `EFG_VERIFY_QUOTA_ENFORCE=true` is set, currently shadow mode).'
      tags:
      - Trust
      security:
      - {}
      - orgApiKey: []
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: 'Receipt id to verify. Accepted formats: `tr_<12hex>` (transcript), `cr_<12hex>` (course receipt), `ws_<12hex>` (work sample), `wn_<12hex>` (Sunday Note), `wl_<12hex>` (wall), `att_<12hex>` (attestation), consent receipt UUID, or audit log UUID. Alias: `receipt_id` is accepted as a fallback query parameter.'
      responses:
        '200':
          description: 'Verification result. `verified: true` with non-PII metadata. Top-level fields vary by receipt kind but always include `verified` (boolean), `id` (string), `issued_by` (string), and `kind` (string). Actual values returned by the code: `family_transcript` (`tr_` ids), `course_receipt` (`cr_`), `work_sample` (`ws_`), `weekly_note` (`wn_`), `wall` (`wl_`), `attestation` (`att_`), `consent_receipt` (consent UUIDs), `event_receipt` (audit log UUIDs), `plan_receipt` (plan receipts), and `revoked` when the issuing family has withdrawn the receipt (carries `revoked: true`, `original_kind`, `revoked_at`; the content is withheld).'
        '402':
          description: 'Free-tier org over monthly evaluation allowance (only when `EFG_VERIFY_QUOTA_ENFORCE=true`; paid plans never receive this). Response body fields: `error` (string), `plan` (string), `included` (number), `used` (number), `hint` (string), `upgrade_url` (string).'
        '404':
          description: 'Not a valid Eformogi receipt. Response shape is uniform (`verified: false`, `id`, `message`). For well-formed prefixes (`tr_`, `ws_`, `wn_`, `wl_`, `cr_`, `att_`) the message names the receipt family (e.g. "No Eformogi work-sample receipt with this id."); unrecognised prefixes and UUIDs receive a generic fallback message. Existence is never confirmed: revoked, deleted, and never-issued ids all return 404.'
        '429':
          description: 'Rate limited. Public path: 10 requests/min/IP.'
      operationId: getApiVerifyReceipt
      x-operation-id-source: derived
  /api/portrait-evidence:
    get:
      summary: Download a transcript's Portrait of a Graduate evidence as a JSON file
      description: 'Public and keyless, like /api/verify-receipt. Reads the transcript through that

        endpoint''s own lookupTranscript (no separate copy of the read, no behavior change

        to /api/verify-receipt) and writes a downloadable file: the student, the transcript

        and its link, the New York Portrait of a Graduate taxonomy and its source, and every

        signed piece of evidence grouped by attribute, each with the evidence kind and

        reference, the course, the signer''s name, role, organization, and sentence, an

        identity note, and a verify link for the underlying course and signature receipts.

        Nothing here is not already on the verify page''s Portrait section: never an email,

        a hash, or a user id. Not metered and not tracked: an export is not a verification.

        Demo samples export like any other record; they are public samples already.'
      tags:
      - Trust
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
          pattern: ^tr_[a-f0-9]{12}$
        description: A family-issued transcript id.
      responses:
        '200':
          description: 'Body: `format` (`eformogi-portrait-evidence/1`), `transcript` ({ id, verify_url, student_name, issued_at, course_count }), `taxonomy` ({ jurisdiction, version, name, source_line, rubric_status }), `evidence_count` (a sum), `attributes` (array of { id, name, description, evidence_count, evidence: array of { evidence_kind, evidence_kind_label, evidence_ref, course_title, term, cr_receipt_id, cr_verify_url, att_id, att_verify_url, signed_at, signer: { name, role, organization, statement, identity_level, identity_source } } }). Served as `Content-Disposition: attachment`.'
        '400':
          description: '`id` is not `tr_` plus 12 hex characters. Body: `error`.'
        '404':
          description: 'Unknown or withdrawn transcript. Existence of a withdrawn transcript is never confirmed by content. Body: `error`.'
        '405':
          description: 'Not a GET. Body: `error`.'
        '429':
          description: 'Rate limited (30 per minute per IP). Body: `error`.'
        '500':
          description: 'The lookup failed. Body: `error`.'
      operationId: getApiPortraitEvidence
      x-operation-id-source: derived
  /api/issue-credential:
    post:
      summary: Issue a Verifiable Credential
      description: 'By default, issues the Eformogi W3C Verifiable Credential shape from `categoryId` and `fields` (both required). With `format: "ob3"`, issues a signed Open Badges 3.0 OpenBadgeCredential for `itemReceiptId` instead: the achievement and its evidence are built entirely from the stored record, never from the request body. Only `itemReceiptId` (required) and `subjectId` (optional) are accepted for that format; any other field in the body is refused with a 400, because the achievement text and the witness evidence are not caller-supplied facts.'
      tags:
      - Trust
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                categoryId:
                  type: string
                  description: Default format only.
                fields:
                  type: object
                  description: Default format only.
                provenance:
                  type: object
                  description: Default format only.
                personName:
                  type: string
                  description: Default format only.
                format:
                  type: string
                  enum:
                  - ob3
                  description: Omit for the default credential shape; "ob3" for the Open Badges 3.0 profile.
                itemReceiptId:
                  type: string
                  pattern: ^(tr|ws|att)_[a-f0-9]{12}$
                  description: 'format "ob3" only, required: a tr_, ws_, or att_ receipt id owned by the authenticated account.'
                subjectId:
                  type: string
                  description: 'format "ob3" only, optional: the holder''s own did: identifier, never an internal account id.'
      responses:
        '200':
          description: Signed W3C Verifiable Credential, or a signed OB3 OpenBadgeCredential when format is "ob3"
        '400':
          description: An unknown format, a malformed itemReceiptId or subjectId, or an ob3-only field carrying a fact that is built from the record
        '401':
          description: Authentication required
        '403':
          description: 'format "ob3": itemReceiptId exists but does not belong to the authenticated account'
        '404':
          description: 'format "ob3": no record with that itemReceiptId'
      operationId: postApiIssueCredential
      x-operation-id-source: derived
  /api/revoke-credential:
    post:
      summary: Revoke a Verifiable Credential
      tags:
      - Trust
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credentialId:
                  type: string
                reason:
                  type: string
              required:
              - credentialId
      responses:
        '200':
          description: Credential revoked
        '403':
          description: Not credential owner
        '409':
          description: Already revoked
      operationId: postApiRevokeCredential
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT access token
    orgApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Institutional org API key. Use "Bearer efg_org_..." or "Api-Key efg_org_..." header. Keys are scoped to specific data categories.