Securing Your Integration

Authentication at a Glance

Symphonix Health exposes two API systems with different auth models. The table below summarises how they compare.

GHARRA Authentication

The GHARRA zero-trust gateway re-authenticates every request. No implicit trust from network location. Choose the auth method that fits your deployment.

Getting API Keys

Create an API key via the billing endpoint. The raw key is returned only once — store it securely.

curl -X POST https://registry.symphonix.health/v1/admin/billing/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "my-org",
    "display_name": "Production Key",
    "tier": "team",
    "scopes": ["gharra:read", "gharra:write"]
  }'

{
  "key_id": "gharra_key_01HXR...",
  "raw_key": "gharra_sk_live_abc123...",
  "org_id": "my-org",
  "tier": "team",
  "scopes": ["gharra:read", "gharra:write"],
  "created_at": "2026-03-29T10:00:00Z"
}

JWT Bearer Authentication

Pass the token in the Authorization header. GHARRA validates tokens against the configured JWKS endpoint.

import httpx

headers = {"Authorization": f"Bearer {token}"}
resp = httpx.get(
    "https://registry.symphonix.health/v1/discover",
    params={"capability": "fhir-r4-patient-search"},
    headers=headers,
)

Set the JWKS endpoint for token validation:

GHARRA_AUTH_MODE=jwt
GHARRA_JWT_JWKS_URI=https://your-idp.example/.well-known/jwks.json

Mutual TLS (mTLS)

For highest security, use certificate-based authentication. Both client and server present X.509 certificates. Configure with:

GHARRA_AUTH_MODE=mtls

Use the token_binding: mtls_cnf_x5t_s256 parameter in discovery queries to find agents that require mTLS.

Demonstration of Proof-of-Possession (DPoP)

DPoP binds access tokens to the cryptographic key held by the client, preventing token replay attacks. Configure with:

GHARRA_AUTH_MODE=dpop

Required Headers for Mutations

All POST and PUT requests to GHARRA require these headers:

Nexus Authentication

All agents in the Nexus mesh sign their requests with JSON Web Tokens (JWT) using HS256.

JWT Structure

Header: {"alg": "HS256", "typ": "JWT"}

Minting Tokens

from shared.nexus_common.auth import mint_jwt

token = mint_jwt(
    subject="did:web:hospital.org:agents:triage",
    secret="your-jwt-secret",
)
print(token)

python -c "from shared.nexus_common.auth import mint_jwt; print(mint_jwt('test', 'dev-secret-change-me'))"

curl -X POST http://localhost:8100/rpc/triage_agent \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: did:web:hospital.org:agents:triage" \
  -d '{"jsonrpc":"2.0","method":"tasks/send","params":{...},"id":1}'

Development Token Endpoint

The Clinician Avatar agent exposes a convenience endpoint for browser-safe tokens during local development:

curl http://localhost:8039/dev/token

DID Verification

Optional DID signature verification is controlled by the DID_VERIFY environment variable. Disabled by default for local development.

DID_VERIFY=true

SDK Authentication

The GHARRA Python SDK handles token management automatically.

from gharra.sdk import GharraClient

async with GharraClient(
    "https://registry.symphonix.health",
    api_key="gharra_sk_live_abc123...",
    org_id="my-org",
) as gharra:
    agents = await gharra.discover("radiology-summarization", jurisdiction="GB")

from gharra.sdk import GharraClient

# Works when GHARRA_AUTH_MODE=disabled (default in dev)
async with GharraClient("http://localhost:8400", org_id="my-org") as gharra:
    agents = await gharra.discover("fhir-r4-patient-search")

Error Handling

from gharra.sdk import GharraClient, GharraError

async with GharraClient("http://localhost:8400", org_id="my-org") as gharra:
    try:
        result = await gharra.invoke(agent_id, payload={...})
    except GharraError as e:
        if e.status == 401:
            print("Authentication failed — check your API key")
        elif e.status == 403:
            print("Insufficient scopes — need gharra:write")

Best Practices