COSTRINITY Auth API

The auth API from COSTRINITY — 14 operation(s) for auth.

GitHub OpenAPI

Operations 14

POST /api/auth/verify-pin Sign in, step 2 of 2: the 6-digit code emailed after the right password #
POST /api/auth/send-pin A new sign-in code for a pending password sign-in #
POST /api/owners/claim Claim by emailed code, step 1: with the claim link's token, bind an email to an… #
POST /api/owners/claim/confirm Claim by emailed code, step 2: verify the code and the password, bind + verify… #
POST /api/owners/claim/begin Check a claim link and exchange it for a 10-minute HttpOnly claim cookie, or… #
GET /api/auth/github/start Start a GitHub round trip (scope read:user, PKCE). Redirects to GitHub #
GET /api/auth/github/callback GitHub returns here. State must match the browser cookie and is used once. #
POST /api/auth/passkey/register/options WebAuthn registration options for a claim (claim cookie) or for adding a… #
POST /api/auth/passkey/register/verify Verify a new passkey and bind it: claims the trial, or adds it to the signed-in… #
POST /api/auth/passkey/login/options WebAuthn sign-in options (no account named; the browser offers its VITNA… #
POST /api/auth/passkey/login/verify Verify a passkey assertion and start a session. #
GET /api/auth/session The signed-in owner, from the session cookie alone. #
GET /api/auth/methods The ways the signed-in owner can sign in (display only: no subject, key or… #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/costrinity-xyz:costrinity-xyz-auth-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

costrinity-xyz-auth-api-openapi.yml Raw ↑
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.