# Endpoint reference

> The public, stable endpoints you register, monitor, and smoke-test — plus a categorized map of the tool's routes.

[Canonical HTML page](https://safeonlineexam.com/docs/reference/routes)

These are the endpoints you interact with as an operator — for Canvas
registration, health checks, monitoring, and smoke tests. The application's
internal API routes are listed at the end for context, but their parameters and
response shapes are implementation details owned by the service.

## Stable public contracts [#stable-public-contracts]

These paths must stay stable — Canvas and managed clients depend on them. Do not
change them without coordinating a Canvas update.

| Endpoint                                     | Purpose                                                                                                       |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `GET /lti/config`                            | Canvas LTI 1.3 JSON configuration document.                                                                   |
| `GET\|POST /lti/login`                       | OIDC login initiation.                                                                                        |
| `GET\|POST /lti/launch`                      | Signed LTI launch handling.                                                                                   |
| `GET /.well-known/jwks.json`                 | Public LTI signing keys.                                                                                      |
| `GET /health`                                | Process liveness.                                                                                             |
| `GET /ready`                                 | Database + schema readiness.                                                                                  |
| `GET /js/canvas-seb-detector.js`             | Stable detector script for theme loaders.                                                                     |
| `GET /js/canvas-seb-theme-loader.js`         | Hosted, quiz-route-limited loader.                                                                            |
| `GET /api/seb/canvas-detector.js`            | Compatibility alias for an existing loader.                                                                   |
| `GET /api/seb/requirement/:courseId/:quizId` | Secret-free detector check; reports an SEB requirement only for a matching enabled, usable stored assessment. |
| `GET /api/oauth2callback`                    | Canvas OAuth redirect URI.                                                                                    |
| `GET /seb/config/:courseId/:contentId.seb`   | One-time assessment configuration download; certificate-encrypted when encryption is enabled.                 |

Content IDs: Classic Quiz `classicquiz_{quizId}`; New Quiz
`newquiz:{courseId}:{assignmentId}`.

## Certificate verification endpoints [#certificate-verification-endpoints]

| Endpoint                                     | Purpose                                     |
| -------------------------------------------- | ------------------------------------------- |
| `GET /seb/config-encryption-certificate.pem` | Active public encryption certificate (PEM). |
| `GET /seb/config-encryption-certificate.cer` | Active public encryption certificate (DER). |

When certificate encryption is enabled, their `x-seb-public-key-hash` header is
what you compare against the client identity during rollout checks. These never
serve private material. In explicit plaintext compatibility mode, both endpoints
return `404`.

## Smoke-test set [#smoke-test-set]

What to curl after any deploy:

```bash
curl -fsS "${TOOL_URL}/health"
curl -fsS "${TOOL_URL}/ready"
curl -fsS "${TOOL_URL}/.well-known/jwks.json"
curl -fsS "${TOOL_URL}/lti/config"
curl -fsS "${TOOL_URL}/js/canvas-seb-detector.js" | head
curl -fsS "${TOOL_URL}/js/canvas-seb-theme-loader.js" | head
```

## Public and status routes [#public-and-status-routes]

| Route                                        | Purpose                                                                                                        |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `GET /`, `GET /login`                        | Public service status and Canvas-launch fallback.                                                              |
| `GET /health`, `/login/health`, `/js/health` | Lightweight health responses.                                                                                  |
| `GET /setup`, `/setup/guide`                 | Public, role-oriented setup handoff (confirms the service responds — not that Canvas stored the registration). |

## Categorized route map [#categorized-route-map]

The tool also exposes authenticated API routes behind the verified LTI/OAuth
boundary. You do not call these directly, but they help when reading logs or
configuring a WAF:

<Accordions>
  <Accordion title="Canvas OAuth">
    `GET /api/oauth2authorize`, `GET /api/oauth2reauthorize`,
    `GET /api/student-session-authorize`, `GET /api/admin/oauth2authorize`,
    `GET /api/oauth2callback`, `GET /api/oauth2status`.
  </Accordion>

  <Accordion title="Root-account administrator (/api/admin)">
    Summary, operational-term and historical course search, connected-course detail,
    course catalog, terms, connect, per-course refresh and reset, controlled password
    reveal, exit-password rotate/reset, code regenerate, SEB enable/disable, and
    tool-preset create/update/delete/assign/reconcile. All require a verified
    root-account administrator principal and a session-bound action token for
    mutations.
  </Accordion>

  <Accordion title="Instructor assessment (/api/quizzes)">
    Read cached assessment/settings views, refresh discovery, read/update course
    defaults, session-bound password reveal, update SEB settings, enable/disable,
    reset-defaults, regenerate-code, and status.
  </Accordion>

  <Accordion title="Student SEB, proof, and exit">
    Config grant + consume, setup check, session-readiness prompt, a secret-free
    detector requirement check, access-proof and one-time access-code redemption,
    approved-tool view, and the validated exit/quit flow. Unbound manual/auto quit
    routes deliberately return `410`.
  </Accordion>

  <Accordion title="Detector diagnostics">
    `POST /api/debug/canvas-detector-trace` accepts sanitized detector diagnostics only
    when debug/diagnostic mode is enabled (never on production).
  </Accordion>
</Accordions>

<Callout>
  The route handlers in the service are the source of truth for parameters and
  response schemas. Treat unlisted query parameters or output fields as
  implementation details that may change.
</Callout>