Vetrix Docs

Authentication

Identity and access for Vetrix: how a person signs in, how they add a second factor, how they mint credentials for scripts, and how Vetrix exchanges identity and access with systems outside it. The pages range from per-account self-service to the admin-settings configuration that enables an external identity provider for the whole instance.

Two pages here have near-identical names and face opposite directions. oauth2-external-providers.md covers Vetrix as an OAuth2 client: Vetrix sends a user out to Google or GitHub and accepts that provider's word on who they are. oauth2-developer-guide.md covers Vetrix as an OAuth2 authorization server: Vetrix issues access tokens to someone else's application so it can call the Vetrix API on a user's behalf. Enabling "Sign in with Google" is the first; writing a tool that reads a user's repositories is the second.

Account credentials

  • Personal access tokens — Create, list, and revoke the long-lived vetrix_… bearer tokens used by scripts and CI, drawn from the eleven scopes between repo:read and admin:system, with the raw value returned only once at creation and an optional expires_at after which the token is rejected.
  • Two-factor authentication (TOTP) — Enrol an RFC 6238 authenticator by scanning the returned otpauth:// URI and confirming a 6-digit code, store the ten single-use backup codes, and disable the factor with the account password, against verification parameters of HMAC-SHA1, a 30-second period, and a ±1-step clock-skew window.

Signing in through an external identity provider

  • Single sign-on (SSO) — The three SSO mechanisms and how far each one ships: OAuth2 external providers are ready to configure, while LDAP / Active Directory and SAML 2.0 need a third-party Go library added and the authenticator implemented and wired at startup before their documented environment keys and service-provider endpoints take effect.
  • OAuth2 external providers — Vetrix as the OAuth2 client: enable "Sign in with Google / GitHub / GitLab / Microsoft" by storing oauth.<provider>.* credentials through admin settings and registering the /api/v1/auth/oauth2/{provider}/callback redirect URI at the provider, then work through the oauth.allow_email_link auto-link toggle and why GitHub's absent email_verified claim makes it unsafe there, the hand-off to TOTP for users with a second factor, the audit actions emitted, and the per-provider kill switch.

Building third-party apps against Vetrix

  • OAuth2 developer guide — Vetrix as the OAuth2 authorization server: register a public or confidential application, run the authorization-code flow with mandatory S256 PKCE, exchange and refresh the vetrix_oat_… and vetrix_ort_… tokens, and call the API under the read: / write: / admin: scope catalog, with refresh-token rotation that revokes an entire token family on replay, RFC 7009 /revoke and confidential-only RFC 7662 /introspect, a full error catalogue, and the admin suspend and token-lifetime levers.