Authentication

The HealthCloud API uses API keys and optional JWT tokens. All communication must use HTTPS. Keys prefixed with hc_live_ are production keys and trigger HIPAA audit logs.

API Keys

Long-lived credentials scoped to your organization. Create and rotate them in the Developer Console.

JWT Tokens

Short-lived tokens (1 hour) with minimal scopes. Recommended for user-facing apps.

HIPAA Audit Logging

All production API calls are logged with caller identity, timestamp, and PHI access patterns.

Key Rotation

Rotate keys at any time without downtime. Old keys remain valid for 24 hours after rotation.

Using API Keys

Pass your API key in the Authorization header as a Bearer token on every request.

curl https://api.healthcloud.ai/v1/organizations \
  -H "Authorization: Bearer hc_live_sk_AbC12xYz9kLmNpQr"

JWT Token Exchange

Exchange your API key for a scoped, short-lived JWT. This limits exposure in user-facing applications.

# Exchange an API key for a short-lived JWT (expires in 1 hour)
curl -X POST https://api.healthcloud.ai/v1/auth/token \
  -H "Authorization: Bearer hc_live_sk_AbC12xYz9kLmNpQr" \
  -H "Content-Type: application/json" \
  -d '{ "scope": ["read:patients", "exec:agents"] }'
200 OK200
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:patients exec:agents",
  "issued_at": "2026-03-18T12:00:00Z"
}

API Key Scopes

When creating a key, select only the scopes your application needs (principle of least privilege).

ScopeDescriptionLevel
read:patientsRead FHIR Patient resourcesStandard
write:patientsCreate and update Patient resourcesStandard
read:observationsRead FHIR ObservationsStandard
write:observationsCreate Observations (e.g. from devices)Standard
exec:agentsExecute clinical AI agentsStandard
exec:workflowsTrigger workflow runsStandard
admin:orgManage organization settings and usersAdmin
admin:billingView and manage billingAdmin
publish:assetsPublish assets to the marketplacePublisher

Unauthorized Response

An invalid, expired, or missing API key returns a 401 Unauthorized response.

401 Unauthorized401
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key.",
    "requestId": "req_abc123xyz",
    "docsUrl": "https://healthcloud.ai/docs/api/authentication"
  }
}

Security Best Practices

  • ✓Store API keys in environment variables, never in source code.
  • ✓Use test keys (hc_test_sk_*) in development and CI to avoid PHI exposure.
  • ✓Create separate keys per environment (dev, staging, production).
  • ✓Enable key rotation reminders every 90 days in the Developer Console.
  • ✓Restrict keys by IP allowlist for server-side integrations.
  • ✓Monitor the HIPAA audit log weekly for unexpected access patterns.