Authentication

User authentication, session management, and profile endpoints.

Base path: /api/auth

Register

POST /api/auth/register

Authentication: None | Rate limit: Auth (50/15min)

Create a new account with email and password.

Request Body

Field	Type	Required	Description
`email`	string	Yes	User email address
`password`	string	Yes	Password (min 8 characters)
`name`	string	No	Display name

Response

json

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "user@example.com"
  }
}

Example

bash

curl -X POST https://api.controlinfra.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepass123"}'

POST /api/auth/login

Authentication: None | Rate limit: Auth (50/15min)

Authenticate with email and password.

Request Body

Field	Type	Required	Description
`email`	string	Yes	User email address
`password`	string	Yes	Password

Response

json

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "...",
    "email": "user@example.com",
    "role": "user"
  }
}

Example

bash

curl -X POST https://api.controlinfra.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "securepass123"}'

Forgot Password

POST /api/auth/forgot-password

Authentication: None | Rate limit: Auth (50/15min)

Request a password reset email.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Account email address

Example

bash

curl -X POST https://api.controlinfra.com/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Reset Password

POST /api/auth/reset-password

Authentication: None | Rate limit: Auth (50/15min)

Reset password using a token from the reset email.

Request Body

Field	Type	Required	Description
`token`	string	Yes	Reset token from email
`password`	string	Yes	New password

GitHub OAuth

GET /api/auth/github

Authentication: None

Redirect to GitHub for OAuth authentication.

Query Parameters

Parameter	Type	Required	Description
`force`	string	No	Set to `"true"` to force re-login (account switch)
`cli`	string	No	Set to `"true"` for CLI OAuth flow
`redirect_uri`	string	No	Localhost callback URL for CLI (must start with `http://127.0.0.1:`)

GitHub OAuth Callback

GET /api/auth/github/callback

Authentication: None

OAuth callback handler. Issues a JWT and redirects to the frontend (or CLI localhost).

Add GitHub Account

GET /api/auth/github/add-account

Authentication: JWT (via query param)

Link an additional GitHub account to the current user.

Query Parameters

Parameter	Type	Required	Description
`token`	string	Yes	Valid JWT token

Get Current User

GET /api/auth/me

Authentication: Bearer token required

Returns the authenticated user's profile.

Response

json

{
  "id": "...",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "user",
  "githubId": "12345",
  "avatar": "https://..."
}

Example

bash

curl -H "Authorization: Bearer TOKEN" \
  https://api.controlinfra.com/api/auth/me

Complete Onboarding

POST /api/auth/complete-onboarding

Authentication: Bearer token required

Mark the onboarding flow as completed for the current user.

Complete Tour

POST /api/auth/complete-tour

Authentication: Bearer token required

Mark the dashboard tour as completed.

List GitHub Accounts

GET /api/auth/github/accounts

Authentication: Bearer token required

List all GitHub accounts linked to the current user.

Set Active GitHub Account

POST /api/auth/github/accounts/active

Authentication: Bearer token required

Switch the active GitHub account.

Request Body

Field	Type	Required	Description
`githubId`	string	Yes	GitHub user ID to set as active

Remove GitHub Account

DELETE /api/auth/github/accounts/:githubId

Authentication: Bearer token required

Remove a linked GitHub account.

Logout

POST /api/auth/logout

Authentication: Bearer token required

Invalidate the current session.

Refresh Token

POST /api/auth/refresh

Authentication: None (uses refresh token)

Exchange a refresh token for a new JWT.

Request Body

Field	Type	Required	Description
`refreshToken`	string	Yes	Valid refresh token

Get Quota Status

GET /api/auth/quota

Authentication: Bearer token required

Returns the current user's usage quota and limits.

Get Credential Rotation Status

GET /api/auth/credential-rotation-status

Authentication: Bearer token required

Check if cloud credentials need rotation.

Response

json

{
  "rotationRequired": false,
  "rotationRecommended": true,
  "daysUntilRequired": 15,
  "lastRotatedAt": "2025-01-01T00:00:00.000Z",
  "thresholds": {
    "warningDays": 30,
    "requiredDays": 90
  }
}

Get Preferences

GET /api/auth/preferences

Authentication: Bearer token required

Returns user preferences (theme, notification settings, etc.).

Update Preferences

PUT /api/auth/preferences

Authentication: Bearer token required

Update user preferences.

Upload Avatar

POST /api/auth/avatar

Authentication: Bearer token required

Upload a profile avatar image.

Generate Download Token

POST /api/auth/download-token

Authentication: Bearer token required

Generate a short-lived token for download endpoints.

Service Account Token

POST /api/auth/service-token

Authentication: Service key (via x-service-key header)

Obtain a JWT for CI/CD service accounts.

Get Deletion Status

GET /api/auth/deletion-status

Authentication: Bearer token required

Check if an account deletion request is pending.

Request Account Deletion

POST /api/auth/request-deletion

Authentication: Bearer token required

Initiate account deletion. A confirmation email is sent with a cancellation link.

Cancel Account Deletion

POST /api/auth/cancel-deletion

Authentication: None (token-based via email link)

Cancel a pending account deletion request.

Request Body

Field	Type	Required	Description
`token`	string	Yes	Cancellation token from email

GitHub App

Get Install URL

GET /api/auth/github-app/install

Authentication: None

Returns the GitHub App installation URL.

GitHub App Callback

GET /api/auth/github-app/callback

Authentication: None

Handles the GitHub App installation callback.

List Installations

GET /api/auth/github-app/installations

Authentication: Bearer token required

List the current user's GitHub App installations.

Set Active Installation

POST /api/auth/github-app/set-active

Authentication: Bearer token required

Set which GitHub App installation to use.

Sync Repositories

POST /api/auth/github-app/sync-repos

Authentication: Bearer token required

Re-sync repositories from the active GitHub App installation.

Uninstall

DELETE /api/auth/github-app/installations/:installationId

Authentication: Bearer token required

Uninstall a GitHub App installation.

CLI Tokens

List CLI Tokens

GET /api/auth/cli-tokens

Authentication: Bearer token required

List all CLI API tokens for the current user.

Create CLI Token

POST /api/auth/cli-tokens

Authentication: Bearer token required

Create a new CLI API token with specified scopes.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Token name
`scopes`	string[]	Yes	Permission scopes
`allRepositories`	boolean	No	Access all repos (default: false)
`repositories`	string[]	No	Specific repository IDs

Response

json

{
  "token": "ci_abc123...",
  "name": "CI Pipeline",
  "scopes": ["repos:read", "scans:trigger"]
}

Revoke CLI Token

DELETE /api/auth/cli-tokens/:tokenId

Authentication: Bearer token required

Revoke a CLI API token.

Authentication ​

Register ​

Request Body ​

Response ​

Example ​

Login ​

Request Body ​

Response ​

Example ​

Forgot Password ​

Request Body ​

Example ​

Reset Password ​

Request Body ​

GitHub OAuth ​

Query Parameters ​

GitHub OAuth Callback ​

Add GitHub Account ​

Query Parameters ​

Get Current User ​

Response ​

Example ​

Complete Onboarding ​

Complete Tour ​

List GitHub Accounts ​

Set Active GitHub Account ​

Request Body ​

Remove GitHub Account ​

Logout ​

Refresh Token ​

Request Body ​

Get Quota Status ​

Get Credential Rotation Status ​

Response ​

Get Preferences ​

Update Preferences ​

Upload Avatar ​

Generate Download Token ​

Service Account Token ​

Get Deletion Status ​

Request Account Deletion ​

Cancel Account Deletion ​

Request Body ​

GitHub App ​

Get Install URL ​

GitHub App Callback ​

List Installations ​

Set Active Installation ​

Sync Repositories ​

Uninstall ​

CLI Tokens ​

List CLI Tokens ​

Create CLI Token ​

Request Body ​

Response ​

Revoke CLI Token ​

Authentication

Register

Request Body

Response

Example

Login

Request Body

Response

Example

Forgot Password

Request Body

Example

Reset Password

Request Body

GitHub OAuth

Query Parameters

GitHub OAuth Callback

Add GitHub Account

Query Parameters

Get Current User

Response

Example

Complete Onboarding

Complete Tour

List GitHub Accounts

Set Active GitHub Account

Request Body

Remove GitHub Account

Logout

Refresh Token

Request Body

Get Quota Status

Get Credential Rotation Status

Response

Get Preferences

Update Preferences

Upload Avatar

Generate Download Token

Service Account Token

Get Deletion Status

Request Account Deletion

Cancel Account Deletion

Request Body

GitHub App

Get Install URL

GitHub App Callback

List Installations

Set Active Installation

Sync Repositories

Uninstall

CLI Tokens

List CLI Tokens

Create CLI Token

Request Body

Response

Revoke CLI Token