Authentication

The RAG API uses two authentication schemes depending on the context.

API Key Authentication

All /api/v1/* endpoints use API key authentication. Pass your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Key Details

• Your API key is shown once at signup. Save it securely.
• Keys are hashed at storage — we cannot recover a lost key.
• If you lose your key, regenerate it from the dashboard. The old key is immediately invalidated.
• One API key per account.

Key Format

API keys use the format rag_live_<random> (e.g., rag_live_abc123...). The prefix helps you identify RAG API keys in your codebase.

Security

• Keys are hashed before storage — we never store raw API keys.
• Always use HTTPS. The API rejects plain HTTP connections.
• Never expose your API key in client-side code. Keep it server-side.
• Rotate your key immediately if you suspect it has been compromised.

Dashboard Authentication (JWT)

The dashboard web application uses email/password authentication with JWT tokens:

Endpoint	Method	Description
/api/auth/signup	POST	Create account, returns JWT + API key
/api/auth/login	POST	Log in, returns JWT
/api/auth/me	GET	Get current account (requires JWT)
/api/auth/api-key/regenerate	POST	Regenerate API key (requires JWT)

JWT tokens are returned in the response body.

Signup

curl -X POST https://api.useragex.com/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "your-secure-password",
    "name": "Jane Developer"
  }'

Response:

{
  "data": {
    "token": "eyJhbG...",
    "api_key": "rag_live_abc123...",
    "account": {
      "id": "acc_a1b2c3d4e5",
      "email": "dev@example.com",
      "name": "Jane Developer",
      "plan": "trial"
    }
  }
}

Login

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

OAuth Login (GitHub & Google)

You can also sign in to the dashboard using your GitHub or Google account. OAuth login is available at app.useragex.com/auth.

How It Works

1. Click “GitHub” or “Google” on the sign-in page.
2. You’re redirected to the provider to authorize access.
3. On success, you’re redirected back to the dashboard with a JWT session.

Account Linking

• New user: If no account exists for your email, a new account is created automatically with a 7-day trial.
• Existing user: If an account with the same email already exists, the OAuth identity is linked to it — no duplicate accounts.
• Returning user: Subsequent OAuth logins match by provider identity and log you in directly.

OAuth Endpoints

Endpoint	Method	Description
/api/auth/github	GET	Redirect to GitHub authorization
/api/auth/github/callback	GET	Handle GitHub callback
/api/auth/google	GET	Redirect to Google authorization
/api/auth/google/callback	GET	Handle Google callback

Note

OAuth accounts receive an API key at creation, but it’s not shown during the OAuth flow. Use the dashboard to view or regenerate your API key after signing in.

Error Responses

Status	Code	Meaning
401	AUTHENTICATION_ERROR	Missing or invalid API key / JWT
403	AUTHORIZATION_ERROR	Valid credentials but insufficient permissions