Authentication

Authentication unlocks AI-validated scans, deep analysis, and cloud features. This guide covers all authentication methods.

Why Authenticate?

---

Authentication Methods

1. Browser OAuth (Recommended)

The easiest method for local development:

oculum login

1. Opens your default browser
2. Sign in with GitHub
3. Authorize Oculum
4. CLI automatically receives credentials

2. API Key

For CI/CD, headless environments, or scripting:

oculum login --api-key ocu_abc123...

Get your API key from Dashboard Settings.

3. Environment Variable

Set OCULUM_API_KEY for automatic authentication:

export OCULUM_API_KEY=ocu_abc123...
oculum scan --depth verified

No explicit login required.

---

Creating an API Key

1. Go to Dashboard Settings
2. Click Create Key
3. Name it descriptively (e.g., "GitHub Actions", "Local Dev")
4. Copy the key immediately (shown only once)
5. Store securely

Best Practices

• Create separate keys for different environments
• Use descriptive names
• Rotate keys periodically
• Revoke unused keys

---

CLI Commands

Check Status

oculum status

Output:

Logged in as: user@example.com
Plan: Pro
Scan depths: local, verified, deep
Credits: 45 / 250 (18%)
Reset date: February 1, 2026

Logout

oculum logout

Removes stored credentials from your machine.

---

Credential Storage

CLI

Credentials are stored in ~/.oculum/credentials.json:

{
  "apiKey": "ocu_...",
  "email": "user@example.com",
  "plan": "pro",
  "expiresAt": "2026-02-01T00:00:00Z"
}

This file is created automatically after login.

VS Code Extension

The VS Code extension uses VS Code's Secret Storage API, which provides secure, encrypted storage.

---

CI/CD Setup

GitHub Actions

env:
  OCULUM_API_KEY: ${{ secrets.OCULUM_API_KEY }}

steps:
  - uses: actions/checkout@v4
  - run: npm install -g @oculum/cli
  - run: oculum scan --depth verified --fail-on high

Add OCULUM_API_KEY to repository secrets:

1. Settings → Secrets and variables → Actions
2. New repository secret
3. Name: OCULUM_API_KEY
4. Value: Your API key

GitLab CI

variables:
  OCULUM_API_KEY: $OCULUM_API_KEY

security-scan:
  script:
    - npm install -g @oculum/cli
    - oculum scan --depth verified

Add the variable in Settings → CI/CD → Variables.

Other CI Systems

Set OCULUM_API_KEY as an environment variable.

---

Troubleshooting

"Authentication required"

Error: Authentication required for verified scans.
Run 'oculum login' to authenticate.

Solution: Run oculum login or set OCULUM_API_KEY.

"Invalid API key"

Error: Invalid API key.

Solutions:

1. Verify the key is correct (no extra spaces)
2. Check the key hasn't been revoked
3. Try creating a new key

Browser Doesn't Open

If oculum login doesn't open a browser:

# Use API key instead
oculum login --api-key YOUR_KEY

Or manually open the URL shown in the terminal.

Re-authenticate

oculum logout
oculum login

---

Security

API Key Security

• Never commit API keys to version control
• Use environment variables or secret managers
• Rotate keys if compromised

Credential File Permissions

The credential file is created with user-only permissions (600).

Revoking Keys

Revoke compromised keys immediately:

1. Go to Dashboard Settings
2. Find the key
3. Click Revoke

---

Plans and Tiers

See Credits & Usage for plan details.

---

Related

• Credits & Usage — Plans and quotas
• CI/CD Setup — Pipeline integration
• VS Code Extension — IDE authentication