Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: VITNA API (Phase 1) Auth API
version: 1.1.0
description: 'The compliance evidence layer for AI agents. Pre-flight compliance checks agents call before they act (consent, breach reportability, EU AI Act classification, cross-border), and audit-grade, signed records of what they did. Phase 1 surface covers region routing labels (one database region is in use today), DPIA/ROPA generation, Data Subject Rights (scoped: answerable only for events linked to a subject via principal_ref at ingest, from the point linkage begins; earlier events are permanently unattributable and cannot be linked retroactively), consent lifecycle, Sahamati AA integration, breach notification, and INR/Razorpay billing for DPDP-IN owners (switched off pending merchant onboarding). Also includes one-command agent self-provisioning (/api/setup, mints a restricted trial key with no signup), a destructive-action safety pre-flight (/api/preflight/action-check), scoped engagement sessions with signed evidence bundles (/api/engagement/*), and account claim by a person, from the claim link (/claim).'
contact:
name: COSTRINITY
email: dpo@costrinity.xyz
url: https://www.costrinity.xyz/
license:
name: Proprietary
url: https://vitna.costrinity.xyz/terms
servers:
- url: https://vitna.costrinity.xyz
description: Production
- url: https://vigil-staging.vercel.app
description: Staging (preview branch)
tags:
- name: Auth
paths:
/api/auth/verify-pin:
post:
summary: 'Sign in, step 2 of 2: the 6-digit code emailed after the right password'
description: Needs the vitna_signin cookie that step 1 (POST /api/owners) set and a same-origin request; without the cookie nothing is read or counted. Any email address in the body is ignored. At most 5 tries per code and 20 a day per owner, each counted before the compare; a code past its 5 tries is refused uncompared until a new one is sent. A right code signs the session cookie and clears vitna_signin. Before 2026-11-02 this route took {email, pin} and a code alone signed in.
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- code
properties:
code:
type: string
pattern: ^\d{6}$
responses:
'200':
description: '{verified:true, owner} with the session cookie'
'400':
description: code_required
'401':
description: signin_expired (no usable pending sign-in), invalid_code or code_expired. A body in the shape this route took before (an email, or a pin) with no pending sign-in gets code code_alone_refused, with error and message both saying how an account that only ever signed in with a code gets back in
'403':
description: origin_rejected
'429':
description: IP rate limited (60 / 10 min), or too_many_attempts
'503':
description: signin_unavailable (a read failed; vitna_signin is kept for another try)
operationId: postApiAuthVerifyPin
x-operation-id-source: derived
/api/auth/send-pin:
post:
summary: A new sign-in code for a pending password sign-in
description: 'No body: the code goes to the address of the account whose password step 1 accepted (the vitna_signin cookie), within 3 codes per 15 minutes and 10 a day. Same-origin requests only. Before 2026-11-02 this route took {email} and sent that address a code that signed in on its own.'
tags:
- Auth
responses:
'200':
description: '{sent:true}'
'401':
description: 'signin_expired: no usable pending sign-in. A body with an email (the shape this route took before) gets code code_alone_refused, with error and message both saying how an account that only ever signed in with a code gets back in'
'403':
description: origin_rejected
'429':
description: IP rate limited (30 / 10 min), or code_send_limit
'503':
description: signin_unavailable (a read failed; vitna_signin is kept) or code_not_sent
operationId: postApiAuthSendPin
x-operation-id-source: derived
/api/owners/claim:
post:
summary: 'Claim by emailed code, step 1: with the claim link''s token, bind an email to an…'
description: 'The claim link''s token (its t= value) is the only proof accepted; owner_id alone is refused. A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. The claim page does not use this route: it claims with GitHub or a passkey. The request also sets the account''s password (at least 12 characters, kept only as a bcrypt hash with the pending claim), which confirm asks for with the code: the account signs in afterwards with that password and a code emailed to it.'
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- owner_id
- email
- token
- password
properties:
owner_id:
type: string
format: uuid
email:
type: string
token:
type: string
description: The t= value of the claim link.
password:
type: string
description: 'The password for the claimed account: at least 12 characters, not the address, not a common one.'
responses:
'200':
description: '{sent:true, owner_id, email_delivery}'
'400':
description: valid owner_id / email required, or password_required (missing, or against the rules for a new password)
'403':
description: claim_by_key_refused, claim_link_invalid or claim_link_expired
'404':
description: not_claimable
'409':
description: already_claimed, claim_link_used, email_in_use, or claim_email_fixed (since 2026-11-01 a code goes only to the address the claim started with)
'429':
description: IP rate limited (20 / 10 min), or claim_code_cap (at most 3 codes a day for one claim, since 2026-11-01)
'503':
description: claim_unavailable (no signing secret; fails closed)
operationId: postApiOwnersClaim
x-operation-id-source: derived
/api/owners/claim/confirm:
post:
summary: 'Claim by emailed code, step 2: verify the code and the password, bind + verify…'
description: 'A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. A pending claim that the claim link did not start (one an API key started before 2026-10-05) is refused the same way, before the code is compared, and wiped. The code and the password given at step 1 are both compared on every try; a wrong code, a wrong password or both get the one answer invalid_code_or_password and count as one of the 5 tries. A pending claim started before claims took a password has none: it is wiped and refused 409 claim_restart_required.'
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- owner_id
- pin
- password
properties:
owner_id:
type: string
format: uuid
pin:
type: string
pattern: ^\d{6}$
password:
type: string
description: The password given at step 1.
responses:
'200':
description: '{claimed:true, owner_id, keys_unlocked} with the session cookie'
'400':
description: valid owner_id / pin / password required; no_claim_in_progress; code_expired
'401':
description: invalid_code_or_password
'403':
description: claim_by_key_refused
'404':
description: not_claimable
'409':
description: not_claimable (not a trial account), claim_link_used, email_in_use, or claim_restart_required
'429':
description: IP rate limited (30 / 10 min), or too_many_attempts
operationId: postApiOwnersClaimConfirm
x-operation-id-source: derived
/api/owners/claim/begin:
post:
summary: Check a claim link and exchange it for a 10-minute HttpOnly claim cookie, or…
description: 'A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. With renew: true, an expired but genuine link for an unclaimed trial that started less than 72 hours ago is renewed once: the old link is spent, a fresh one is minted and the claim cookie is set for it. The fresh link is never in the body. The claim page sends this only when the person chooses Get a fresh link; checking a link never renews it.'
tags:
- Auth
requestBody:
content:
application/json:
schema:
type: object
properties:
owner_id:
type: string
format: uuid
token:
type: string
description: The t= value of the claim link. Omit both fields to resume from the claim cookie.
renew:
type: boolean
description: true renews an expired link (see above). Ignored for a link that has not expired.
responses:
'200':
description: '{claimable:true, owner_id, link_expires_at, trial:{provisioned_at, agents}} and Set-Cookie vitna_claim; after a renewal also renewed:true, with no link in the body'
'400':
description: invalid_request
'403':
description: 'claim_by_key_refused, claim_link_invalid (a forged or incomplete link, with renew or without), claim_link_not_renewable (renew: true refused for a genuine link: renewed or spent already, the trial claimed, or its 72 hours passed; the same message for each, renewable:false and fresh_link with the new-trial command, never a link), claim_link_expired (links last 24 hours; renewable:true when the page can renew it once, otherwise fresh_link says how to start a new trial), claim_session_expired on resume, or origin_rejected'
'409':
description: already_claimed or claim_link_used
'429':
description: IP rate limited (20 / 10 min)
'503':
description: claim_unavailable (no signing secret; fails closed)
operationId: postApiOwnersClaimBegin
x-operation-id-source: derived
/api/auth/github/start:
get:
summary: Start a GitHub round trip (scope read:user, PKCE). Redirects to GitHub
description: 'For intent=claim: A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. That refusal is JSON, not a redirect.'
tags:
- Auth
parameters:
- name: intent
in: query
schema:
type: string
enum:
- signin
- claim
- link
responses:
'302':
description: To GitHub, with Set-Cookie vitna_oauth (state, Lax, 10 min)
'303':
description: Back to /dashboard?auth_error= or /claim?error= (github_unavailable, claim_session_expired, reauth_required, rate_limited)
'403':
description: claim_by_key_refused (intent=claim with an API key)
operationId: getApiAuthGithubStart
x-operation-id-source: derived
/api/auth/github/callback:
get:
summary: GitHub returns here. State must match the browser cookie and is used once.
description: 'For a claim round trip: A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. That refusal is JSON, not a redirect, and the state is not spent. A link round trip is refused (reauth_required) when the session that started it has been signed out, or ended by the owner''s session cutoff, since; a link ends every other session of the account first, and this browser gets a replacement that keeps its sign-in time; when they cannot be ended nothing is added (github_failed).'
tags:
- Auth
parameters:
- name: code
in: query
schema:
type: string
- name: state
in: query
schema:
type: string
responses:
'303':
description: '/dashboard?signed_in=github, ?linked=github or ?from=claim on success; otherwise ?auth_error= / /claim?error= with oauth_state_invalid, github_not_linked, identity_in_use, github_cancelled, github_failed, reauth_required, or link_unconfirmed (a link that ended the other sessions and then did not finish: it may or may not have been added)'
'403':
description: claim_by_key_refused (a claim round trip with an API key)
operationId: getApiAuthGithubCallback
x-operation-id-source: derived
/api/auth/passkey/register/options:
post:
summary: WebAuthn registration options for a claim (claim cookie) or for adding a…
description: 'The options ask for user verification (userVerification: required). For flow claim: A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim.'
tags:
- Auth
security:
- Session: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- flow
properties:
flow:
type: string
enum:
- claim
- link
responses:
'200':
description: '{options} and Set-Cookie vitna_webauthn (challenge, 5 min)'
'400':
description: passkeys_unavailable_here or invalid_request
'401':
description: claim_session_expired or no_session
'403':
description: claim_by_key_refused (flow claim with an API key), reauth_required or origin_rejected
'409':
description: already_claimed
'429':
description: IP rate limited (30 / 10 min)
operationId: postApiAuthPasskeyRegisterOptions
x-operation-id-source: derived
/api/auth/passkey/register/verify:
post:
summary: 'Verify a new passkey and bind it: claims the trial, or adds it to the signed-in…'
description: 'A response whose authenticator data does not have the UV (user verified) flag set is refused 400 passkey_verification_failed. For flow claim: A request carrying an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside the claim link or a claim cookie) is refused 403 claim_by_key_refused: a person claims from the claim link in the MCP server log, and an API key cannot start or finish a claim. For flow link, every other session of the account ends first, and this browser gets a replacement that keeps its sign-in time; when they cannot be ended nothing is added (503), and a session another change ended meanwhile adds nothing (401 no_session).'
tags:
- Auth
security:
- Session: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- flow
- response
properties:
flow:
type: string
enum:
- claim
- link
response:
type: object
label:
type: string
responses:
'200':
description: '{claimed:true, owner} with a session cookie, or {linked:true, method}'
'400':
description: passkey_verification_failed, challenge_expired or invalid_request
'401':
description: claim_session_expired or no_session
'403':
description: claim_by_key_refused (flow claim with an API key), reauth_required or origin_rejected
'409':
description: challenge_used, identity_in_use, already_claimed, claim_link_used or too_many_methods
'429':
description: IP rate limited (30 / 10 min)
'503':
description: passkeys_unavailable
operationId: postApiAuthPasskeyRegisterVerify
x-operation-id-source: derived
/api/auth/passkey/login/options:
post:
summary: WebAuthn sign-in options (no account named; the browser offers its VITNA…
description: 'The options ask for user verification (userVerification: required).'
tags:
- Auth
responses:
'200':
description: '{options} and Set-Cookie vitna_webauthn (challenge, 5 min)'
'400':
description: passkeys_unavailable_here
'403':
description: origin_rejected
'429':
description: IP rate limited (30 / 10 min)
operationId: postApiAuthPasskeyLoginOptions
x-operation-id-source: derived
/api/auth/passkey/login/verify:
post:
summary: Verify a passkey assertion and start a session.
description: An assertion whose authenticator data does not have the UV (user verified) flag set is refused 401 passkey_verification_failed.
tags:
- Auth
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- response
properties:
response:
type: object
responses:
'200':
description: '{owner} with a session cookie'
'400':
description: challenge_expired or invalid_request
'401':
description: passkey_not_recognized or passkey_verification_failed
'409':
description: challenge_used
'429':
description: IP rate limited (30 / 10 min)
operationId: postApiAuthPasskeyLoginVerify
x-operation-id-source: derived
/api/auth/session:
get:
summary: The signed-in owner, from the session cookie alone.
description: 'A request that carries an API key in any header form is refused 403 session_required, with or without a session cookie beside it: the answer is the owner''s email address, name and plan.'
tags:
- Auth
security:
- Session: []
responses:
'200':
description: '{owner:{id, email, name, plan, created_at, plan_expires_at?}}'
'401':
description: no_session
'403':
description: 'session_required: the request carried an API key'
'429':
description: IP rate limited (120 / 10 min)
operationId: getApiAuthSession
x-operation-id-source: derived
/api/auth/methods:
get:
summary: 'The ways the signed-in owner can sign in (display only: no subject, key or…'
tags:
- Auth
security:
- Session: []
responses:
'200':
description: '{methods:[{id, provider, label, created_at, last_used_at}], password, password_second_step, recent_auth}. password is true when the password signs in: a real address on a claimed account, with a code that can be emailed there and a mailed code entered there before, at a sign-in or an email claim (''email_code''; an address an operator marked verified, or one an operator-issued claim code was given for, counts once a mailed code is entered), or an address whose mail Google handles (Gmail or a Google Workspace domain) while no code can reach Gmail (''none''). An emailed code alone is not a way to sign in, so it is not listed.'
'401':
description: no_session
'429':
description: IP rate limited (60 / 10 min)
operationId: getApiAuthMethods
x-operation-id-source: derived
/api/auth/methods/unlink:
post:
summary: Remove a GitHub account or passkey (session signed in within 10 minutes).
tags:
- Auth
security:
- Session: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- identity_id
properties:
identity_id:
type: string
responses:
'200':
description: '{removed:true, remaining}, with session_ended:true and no new session cookie when another change ended this session meanwhile (sign in again)'
'401':
description: 'no_session, or session_ended: another change to how the account signs in ended this session meanwhile, and nothing was removed'
'403':
description: reauth_required or origin_rejected
'404':
description: not_found
'409':
description: last_method
'429':
description: IP rate limited (10 / 10 min)
'503':
description: 'unavailable: the other sessions could not be ended, and nothing was removed; or sessions_not_ended: the method was removed, but the second sign-out of the other sessions could not be written (sign in again and repeat a change to how you sign in)'
operationId: postApiAuthMethodsUnlink
x-operation-id-source: derived
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-vigil-key
description: 'Per-agent API key. Format: vitna_<64-char-hex>; legacy vigil_ keys remain valid. Send on /api/ingest.'
Bearer:
type: http
scheme: bearer
bearerFormat: vitna_<key> (legacy vigil_<key> accepted)
description: 'Same key as x-vigil-key, sent as `Authorization: Bearer <key>`.'
Session:
type: apiKey
in: cookie
name: vigil_session
description: 'Operator dashboard session cookie. Set by a sign-in: the second step of a password sign-in (/api/auth/verify-pin), or, for an address whose mail Google handles (Gmail or a Google Workspace domain) while VITNA''s mail cannot reach Gmail, the password alone (/api/owners); GitHub; a passkey; or a claim.'
CronSecret:
type: http
scheme: bearer
description: Bearer ${CRON_SECRET}. Only the Vercel cron infrastructure should hold this.