Authentication

All MedTWIN API requests require authentication.

Authentication Methods

API Keys

Best for server-to-server integrations.

curl -H "Authorization: Bearer mt_live_abc123..." \
  https://api.medtwin.ai/v1/projects

Session Tokens

Best for browser-based applications.

curl -H "Authorization: Session sess_xyz789..." \
  https://api.medtwin.ai/v1/projects

Getting an API Key

Via Dashboard

Log in to app.medtwin.ai
Go to Settings → API Keys
Click Create API Key
Name your key (e.g., "Production Server")
Set permissions (read, write, admin)
Copy and save the key

Save Your Key

The full API key is only shown once. Store it securely.

Via API (Authenticated)

curl -X POST https://api.medtwin.ai/v1/api-keys \
  -H "Authorization: Session YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "permissions": ["read", "write"]
  }'

Key Types

Test Keys

Prefix: mt_test_
Use in development/staging
Limited rate limits
Can access test data only

Live Keys

Prefix: mt_live_
Use in production
Full rate limits
Access to real data

Key Permissions

Permission	Capabilities
`read`	View projects, data, analyses
`write`	Create/update projects, run analyses
`delete`	Delete projects and data
`admin`	Manage team members, billing

Scoped Keys

Create keys limited to specific projects:

{
  "name": "Study A Server",
  "permissions": ["read", "write"],
  "scope": {
    "projects": ["proj_abc123", "proj_def456"]
  }
}

Key Management

List Keys

GET /v1/api-keys

Revoke Key

DELETE /v1/api-keys/{key_id}

Rotate Key

POST /v1/api-keys/{key_id}/rotate

Session Authentication

For browser apps, use session-based auth:

POST /v1/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "session_token": "sess_xyz789...",
  "expires_at": "2026-01-30T12:00:00Z"
}

Logout

POST /v1/auth/logout
Authorization: Session sess_xyz789...

Security Best Practices

Never Expose Keys

Don't commit keys to version control
Don't include in client-side code
Use environment variables

Environment Variables

# .env file
MEDTWIN_API_KEY=mt_live_abc123...

import os
from medtwin import Client

client = Client(api_key=os.environ['MEDTWIN_API_KEY'])

Key Rotation

Rotate keys regularly:

Create new key
Update your application
Verify new key works
Revoke old key

Error Responses

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Causes:

Missing Authorization header
Invalid API key
Expired API key

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have required permissions"
  }
}