Authentication & requests
Veriglyph has public reference endpoints, signed-in product endpoints, and admin-only workflow endpoints. Use the access mode for the route you are calling; there is no separate API credential to provision.
same-origin /api/*JSON responses01 / access modes
Know the boundary
The public documentation APIs are intentionally callable without a session. Routes that read or change account-owned data use the Better Auth session established by the app’s email-and-password sign-in flow. Admin routes add a role check on top of that session.
| Mode | Representative routes | Behavior |
|---|---|---|
| Public | /api/check /api/inventory/pages/[slug] /api/spec-diffs | No session is required. Invalid JSON or fields still return a validation error; a missing inventory slug returns 404. |
| Signed in | /api/repos /api/repos/[id]/activity /api/usage | The request must carry the current Better Auth session cookie. Missing or expired sessions return 401 Unauthorized; owner-scoped lookups do not expose another user’s records. |
| Admin | /api/admin/overview /api/admin/drafts /api/drafts/run | A valid session is not enough: user.role must be admin. No session returns 401; a signed-in non-admin returns 403 Forbidden. |
02 / session
Sign in once, stay same-origin
Sign in or create an account at /login or /signup with email and password. Better Auth handles the /api/auth/* calls and sets the session cookie on this app’s origin. The installed client intentionally uses a relative auth base, so the cookie follows the host that served the app.
credentials: 'include' option below is useful when your request wrapper sets credentials deliberately; it does not create a token or replace the Better Auth cookie.fetch('/api/repos', {
credentials: 'include',
headers: { Accept: 'application/json' },
})03 / headers
Send JSON when the route reads JSON
Use Content-Type: application/json for POST requests with JSON bodies. An Accept: application/json header makes the desired response format explicit; the route handlers return JSON regardless. GET requests with path or query parameters do not need a body.
curl "${APP_URL}/api/check" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data '{"code":"navigator.geolocation.getCurrentPosition(() => {})"}'| Route | Input | Shape |
|---|---|---|
| POST /api/check | JSON body | { code: string }; the code is capped at 50 KB. |
| POST /api/repos | JSON body | { repoUrl: string, label?: string }; the signed-in user is the owner. |
| GET /api/inventory/pages/[slug] | Path | Replace slug with the documented page identifier; there is no body or query parameter. |
| GET /api/repos/[id]/activity | Path + query | Replace id; optional threshold and bodyMaxChars query parameters tune triage input. |
| GET /api/admin/drafts | Query | Optional status: pending_review (default), published, rejected, or all. |
04 / protected examples
Carry the session into product calls
After the browser sign-in succeeds, the same-origin cookie is enough for protected calls. A command-line client must supply the session cookie it obtained from a same-origin sign-in; do not copy a browser cookie into source control or logs.
curl "${APP_URL}/api/repos" \
-H "Content-Type: application/json" \
-H "Cookie: <same-origin Better Auth session cookie>" \
--data '{"repoUrl":"https://github.com/example/project","label":"Example"}'curl "${APP_URL}/api/repos/<repo_id>/activity?threshold=0.6&bodyMaxChars=500" \
-H "Cookie: <same-origin Better Auth session cookie>"05 / admin behavior
Admin is a role, not another credential
Admin API handlers call getSessionUser(), then require user.role === 'admin'. Use the same session-cookie setup as any signed-in call; the role is assigned by the app’s Better Auth configuration, not by a request header or body field.
curl "${APP_URL}/api/admin/drafts?status=all" \
-H "Accept: application/json" \
-H "Cookie: <same-origin Better Auth session cookie>"| 401 | { error: "Unauthorized" } — no valid Better Auth session was present. |
| 403 | { error: "Forbidden" } — the session exists, but its user is not an admin. |
06 / explicit limits
Credentials this API does not implement
Authorization: Bearer tokens, CSRF-token headers, or invented third-party credential flows in this app. Do not add one to a request and assume it will be checked. Authenticate through the existing same-origin Better Auth email-and-password flow, then send the resulting session cookie to the protected route.