Authentication

The Elia API supports two authentication methods. Use JWT tokens for interactive sessions (web UI, testing) and API keys for programmatic access.

Authentication Methods

Both methods are accepted on all company data endpoints. Self-service endpoints (/api/v1/auth/*) require JWT only.

Registration

Create an account with email and password. New accounts start on the Free tier with 100 credits.

curl -X POST /api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Doe", "email": "jane@fund.com", "password": "secure-password-8+"}'

The response includes a JWT token (auto-login) and your user profile:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2026-04-02T15:00:00Z",
  "user": {
    "id": "01968a1c-...",
    "name": "Jane Doe",
    "email": "jane@fund.com",
    "tier": "Free"
  }
}

Login

curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@fund.com", "password": "secure-password-8+"}'

JWT tokens expire after 60 minutes by default.

API Keys

API keys are the primary method for programmatic access. They don't expire by default (unless you set an expiry) and are tied to your account's credit balance.

Create a Key

curl -X POST /api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production"}'

The raw key (e.g. erip_abc123...) is returned once — store it securely. Only a SHA-256 hash is stored server-side.

Use a Key

Include it in the X-Api-Key header on every request:

curl /api/v1/companies/search?name=Siemens \
  -H "X-Api-Key: erip_YOUR_KEY"

Manage Keys

• GET /api/v1/auth/api-keys — list your keys (metadata only)
• DELETE /api/v1/auth/api-keys/{keyId} — revoke a key (immediate)

Credits

Every API call consumes credits based on the endpoint:

Credit costs are configurable and returned in response headers:

X-Credits-Remaining: 95
X-Credits-Cost: 5

When credits are exhausted, the API returns 402 Payment Required.

Check Your Balance

curl /api/v1/auth/credits \
  -H "Authorization: Bearer YOUR_JWT"