Authentication

MedRAG uses two authentication mechanisms, each serving a different access pattern:

REST API: API Keys

Every request to the REST API must include a valid API key in the Authorization header.

API Key Format

medrag_sk_<random>

Usage

curl -H "Authorization: Bearer medrag_sk_..." \
     https://api.medrag.eu/v1/query \
     -d '{"query": "blood pressure targets"}'

Managing API Keys

From the web portal:

• Create — Generate a new key with a specific role (read, write, admin)
• Revoke — Immediately invalidate a key
• List — View all keys with creation dates and last-used timestamps

Roles

MCP Endpoint: OAuth Access Tokens

The MCP endpoint (https://medrag.eu/mcp/sse) does not accept API keys. It accepts short-lived OAuth access tokens issued by MedRAG’s authorization server.

For Backend Agents and CI/CD (available now)

Use OAuth Client Credentials for non-interactive access. OAuth applications are currently registered by MedRAG support on request; you receive a client_id and a client_secret:

curl -X POST https://medrag.eu/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=medrag_client_xxxx" \
  -d "client_secret=$SECRET" \
  -d "scope=mcp:read"

See MCP Integration → Enterprise for full details.

For Desktop AI Clients (Claude, Cursor, VS Code) — coming soon

Interactive sign-in from desktop AI clients (browser login, tokens managed by the client) is not available yet. Adding the MedRAG URL to a desktop client’s MCP configuration will not work until it ships. Use the REST API with an API key in the meantime.

OAuth Scopes

Web Portal Account

You sign in to the web portal with your account’s email address and password. The portal is where you manage API keys, billing and settings.

Forgotten Password

1. On the login page, choose Forgot password? and enter your account’s email address.
2. If the address belongs to an account, a reset link is emailed to it. The page shows the same message either way, so it can’t be used to find out which addresses are registered. The link expires after 1 hour and works once.
3. Open the link and choose a new password (at least 8 characters).

Resetting your password signs you out of the portal everywhere, so any portal session someone else may hold is signed out too. API keys and OAuth clients are not affected. Revoke them separately if you think they are compromised.

You can request at most 3 reset emails per hour. If the email doesn’t arrive, check your spam folder before requesting another.

Security Best Practices

API Keys (REST)

• Never commit API keys to version control
• Store keys in environment variables or a secrets manager
• Rotate keys periodically
• Revoke any key that may have been exposed
• Use the minimum required role for each key

OAuth (MCP)

• Access tokens expire in 15 minutes; request a new one before expiry
• Store the client_secret in your CI system’s secrets manager and never commit it to version control
• Contact support to revoke the OAuth application if the secret may have been exposed
• Scope your OAuth applications to the minimum permissions needed
• Enterprise: use sub-tenant scoping to enforce data isolation

Leaked Key Protection

MedRAG is enrolled in the GitHub Secret Scanning Partner Program. If you accidentally push a medrag_sk_* key to a public GitHub repository:

1. GitHub detects the key instantly
2. MedRAG automatically revokes it
3. You receive an email notification with the repository where it was found

This protects you even if you don’t notice the leak yourself. This protection covers API keys only; keep OAuth client secrets out of version control as well.