Authentication

AVYCENNA supports several authentication methods. Email OTP is recommended for interactive use (dashboard, manual API testing). API keys are best for server-to-server integrations and automation.

Email OTP (Passwordless)

The recommended login method for doctors. No password to remember or rotate — just verify your email with a one-time code.

Send an OTP

curl -X POST https://api.avycenna.com/api/v1/auth/otp/send \
  -H "Content-Type: application/json" \
  -d '{"email": "doctor@clinic.com"}'

Response:

{
  "message": "OTP sent to doctor@clinic.com",
  "expires_in_minutes": 10
}

Verify the OTP

curl -X POST https://api.avycenna.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@clinic.com",
    "otp": "847291"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_a9f3c81e7b2d4e6f...",
  "token_type": "bearer",
  "expires_in": 900,
  "user": {
    "id": "usr_7jRtHvBk",
    "email": "doctor@clinic.com",
    "name": "Dr. Sarah Chen",
    "role": "doctor"
  }
}

Access token: JWT, valid for 15 minutes
Refresh token: Opaque string, valid for 30 days

Email/Password

For accounts created with a password (e.g., via the registration flow).

Register

curl -X POST https://api.avycenna.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dr. Sarah Chen",
    "email": "doctor@clinic.com",
    "password": "a-strong-password"
  }'

curl -X POST https://api.avycenna.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "doctor@clinic.com",
    "password": "a-strong-password"
  }'

Response: same shape as OTP verify — returns access_token and refresh_token.

Token Refresh

Access tokens expire after 15 minutes. Use the refresh token to get a new pair without re-authenticating. Refresh tokens rotate on each use — store the new refresh token from the response.

curl -X POST https://api.avycenna.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "rt_a9f3c81e7b2d4e6f..."}'

Response:

{
  "access_token": "eyJhbGci...",
  "refresh_token": "rt_newtoken...",
  "token_type": "bearer",
  "expires_in": 900
}

Refresh tokens rotate on use. If you call /auth/refresh twice with the same refresh token, the second call will fail. Always replace your stored refresh token with the one returned in the response.

Logout

Invalidate a refresh token (logs the user out of that session):

curl -X POST https://api.avycenna.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "rt_a9f3c81e7b2d4e6f..."}'

Google OAuth

For accounts that prefer signing in with Google.

Initiate OAuth Flow

Redirect the user to:

GET https://api.avycenna.com/api/v1/auth/oauth/google

This redirects to Google's OAuth consent screen.

OAuth Callback

Google redirects back to:

GET https://api.avycenna.com/api/v1/auth/oauth/google/callback?code=...&state=...

The backend exchanges the code for Google tokens, creates or links the AVYCENNA account, and redirects to the dashboard with session tokens set as cookies (or appended to the redirect URL for native clients).

API Keys

API keys are long-lived credentials for server-to-server integrations. They don't expire until deleted and don't require token rotation.

Create an API Key

curl -X POST https://api.avycenna.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EHR Integration - Production",
    "scopes": ["read:health", "read:users"]
  }'

Response:

{
  "id": "key_3mPqRsTu",
  "name": "EHR Integration - Production",
  "key": "avk_a7f3c91e8b2d4e6f1a9c3b5d...",
  "scopes": ["read:health", "read:users"],
  "created_at": "2026-06-30T14:00:00Z",
  "last_used_at": null
}

The full API key value (avk_...) is only shown once at creation time. AVYCENNA stores only a SHA-256 hash of the key — it cannot be retrieved again. Copy it immediately and store it in a secrets manager.

Use an API Key

Pass the key in the X-API-Key header:

curl https://api.avycenna.com/api/v1/grants/outgoing \
  -H "X-API-Key: avk_a7f3c91e8b2d4e6f1a9c3b5d..."

Available Scopes

Scope	What It Allows
`read:health`	Read check-ins, symptoms, medications (for granted patients)
`write:health`	Ingest wearable data, create check-ins
`read:users`	Read user profiles
`admin`	Full access — use with extreme caution

List API Keys

curl https://api.avycenna.com/api/v1/api-keys \
  -H "Authorization: Bearer eyJhbGci..."

Delete an API Key

curl -X DELETE https://api.avycenna.com/api/v1/api-keys/key_3mPqRsTu \
  -H "Authorization: Bearer eyJhbGci..."

Deletion is immediate. Any system using that key will start receiving 401 Unauthorized responses.

Current User

Fetch your account and profile at any time:

curl https://api.avycenna.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

Response:

{
  "user": {
    "id": "usr_7jRtHvBk",
    "email": "doctor@clinic.com",
    "name": "Dr. Sarah Chen",
    "role": "doctor",
    "created_at": "2026-01-15T09:00:00Z"
  },
  "profile": {
    "specialty": "Internal Medicine",
    "institution": "City Medical Center",
    "phone": null
  }
}

Authentication

On this page