ramen ai | Documentation
arrow_back Back to Dashboard GitHub (opens in a new tab)

Authentication

API keys, Bearer tokens, and scope-based access control for production deployments.

API Keys

Every request to the ramen ai API must include a valid API key. Keys are generated in the Settings → API Keys section of your dashboard and are scoped to a specific workspace. 

# Your key is passed as a standard Bearer token
curl -X POST https://api.ramenai.dev/api/v1/evaluate \
  -H "Authorization: Bearer ramen_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello world"}'

Key Scopes

API keys must be scoped for production use. Scopes follow a resource:action pattern and enforce least-privilege access at the API gateway level.

Scope Grants Access To
paas:evaluate The /evaluate endpoint — required for all production traffic
paas:audit The /audit endpoint — read-only access to evaluation logs
admin:read Dashboard data (experts, guardrails, master prompts)
admin:write Create/update/delete dashboard resources

Production rule: Your backend service should use a key scoped to paas:evaluate only. Never expose admin:write keys in client-side code or CI/CD logs.

Bearer Token Format

All keys follow the format ramen_sk_<environment>_<random>. The environment prefix tells you which tier the key targets:

  • ramen_sk_live_... — Production environment
  • ramen_sk_test_... — Sandbox environment (rate-limited, no billing)

SDK Authentication

When using @ramen-ai/node-core, pass your key when constructing the client. Keep the key in a server-side environment variable and provide at least one bundle or policy for every evaluation. 

import { RamenClient } from '@ramen-ai/node-core';

const ramen = new RamenClient({
  apiKey: process.env.RAMEN_API_KEY!,
});

const verdict = await ramen.evaluateCompliance(candidateOutput, {
  bundleIds: ['ramen__shield_core_it'],
});

RBAC & Workspace Isolation

Each workspace in ramen ai is a fully isolated tenant. API keys are bound to a single workspace and cannot access resources in other workspaces. Within a workspace, user roles control dashboard access:

  • Owner — Full access. Can manage billing, API keys, and team members.
  • Admin — Can create and deploy experts, guardrails, and master prompts.
  • Developer — Can view resources and use the evaluate endpoint.
  • Auditor — Read-only access to the compliance ledger and audit logs.

Key Rotation

Rotate keys from the dashboard at any time. When you rotate a key, the old key remains valid for a 5-minute grace period to allow zero-downtime deployments. After the grace period, the old key is permanently revoked.

Next Steps

Documentation