Authentication & Security

Authentication is the front door for CredVault. It protects the dashboard, API, CIE CLI, Coder handoff, Pragma auth bridge, billing, and admin workflows.

User-Facing Flow

Users normally see authentication in these places:

User action	Page or command	Backend route
Create an account	`/signup` or `cie signup`	`POST /api/auth/signup`
Sign in	`/signin` or `cie login`	`POST /api/auth/signin`
Continue with Google	Sign-in page	`GET /api/auth/google`
Continue with GitHub	Sign-in page	`GET /api/auth/github`
Read current profile	Dashboard load	`GET /api/auth/profile`
Validate session	Dashboard/CLI	`GET /api/auth/me`
Sign out	Account menu	`POST /api/auth/logout`
Reset password	Forgot password page	`POST /api/auth/forgot-password`, `POST /api/auth/reset-password`
Select plan	Plan choice page	`POST /api/auth/plan-choice`

How It Works

The user submits credentials or starts OAuth.
The backend validates the user and tenant.
A session token is returned to the frontend or CLI.
The token is sent as a Bearer token on protected API calls.
Middleware checks the token before protected routes continue.
Activity logging records sensitive actions like signup, signin, logout, plan selection, and password changes.

Most protected backend routes use authentication middleware before accessing user data.

Session Token Example

After signing in, API requests use this format:

Terminal

Test in API explorer

curl https://credvault-production.up.railway.app/api/auth/me \
  -H "Authorization: Bearer <your-session-token>"

What you should seeA JSON response, an HTTP status, or a clear authentication or permission error.

You can test this from the browser by opening /api-docs, pressing Authorize, and pasting the Bearer token.

API Key vs Session Token

Use a session token when acting as a signed-in user:

Example

Dashboard pages
CIE login session
Profile and billing pages
Team and account settings

What you should seeA browser login prompt or terminal confirmation that your CredVault session is active.

Use an API key when a backend service or external application needs controlled access:

Example

Server-to-server data reads/writes
Automation jobs
Webhook consumers
Internal integrations

Security Controls In Code

CredVault currently has these controls around authentication:

Rate limits for signin, signup, password reset, and general API traffic
Password hashing and credential validation
OAuth routes for Google and GitHub
WebAuthn/passkey routes under /api/webauthn
Token validation middleware on protected routes
IP allowlist enforcement on sensitive profile and API-key paths
Activity logs for important authentication events
Logout and logout-all routes
Suspicious activity detection middleware

WebAuthn And Passkeys

Passkeys are exposed through the WebAuthn backend route group:

Example

/api/webauthn

Use passkeys for stronger login security where supported. Passkeys are better than SMS-based MFA because they resist phishing and do not depend on mobile carrier security.

Test It

Use these checks during QA:

Terminal

# Sign in from the CLI
cie login

# Confirm the stored session
cie whoami

# Test the API from the CLI environment
cie doctor

What you should seeA browser login prompt or terminal confirmation that your CredVault session is active.

Browser checks:

Example

1. Open /signin
2. Sign in with email/password
3. Open /api-keys
4. Confirm the page loads without redirecting back to signin
5. Open /logs and confirm signin activity is present

API checks:

Terminal

Test in API explorer

curl https://credvault-production.up.railway.app/api/auth/profile \
  -H "Authorization: Bearer <your-session-token>"

What you should seeA JSON response, an HTTP status, or a clear authentication or permission error.

Common Failures

Symptom	Likely cause	Fix
User is sent back to signin	Missing or expired token	Sign in again
CLI says session expired	Stored token is invalid	Run `cie login`
OAuth callback fails	OAuth app callback URL mismatch	Check provider settings
Profile request fails	Token missing or IP allowlist blocked request	Check token and security policy
Plan page cannot continue	Plan-choice user context missing	Sign in through CredVault first

Best Practices

Do not store API keys in frontend code.
Use session tokens for user actions and API keys for server automation.
Rotate API keys used by production services.
Use passkeys or MFA for admin users.
Review /logs after authentication changes.
Keep OAuth callback URLs aligned with production and staging domains.