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 stored as SHA-256 hashes — 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 (V1).

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 with SHA-256 before storage (not bcrypt — API keys are lookup tokens, not passwords).
• 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. The dashboard stores them for session management.

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"
  }'

Error Responses

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