Authentication

FHIRfly supports multiple authentication methods to fit different use cases.

Authentication Methods

API Keys (Simple Credentials)

The simplest way to authenticate. Create an API key in your dashboard and include it with every request.

Setup

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({ apiKey: "ffly_sk_live_abc123..." });

// The SDK sends the API key via the x-api-key header automatically
const ndc = await client.ndc.lookup("0069-0151-01");
console.log(ndc.data.brand_name);

Creating an API Key

1. Go to Dashboard → Credentials
2. Click Create Credential
3. Select Simple (API Key)
4. Choose your scopes (e.g., ndc.read, npi.read)
5. Copy your API key (shown only once!)

API Key Format

ffly_sk_live_abc123...  # Production key
ffly_sk_test_abc123...  # Test/sandbox key

OAuth2 Client Credentials

For enterprise applications that need short-lived tokens and stricter security.

Setup

import { Fhirfly } from "@fhirfly-io/terminology";

const client = new Fhirfly({
  clientId: "ffly_client_...",
  clientSecret: "ffly_secret_...",
  // tokenUrl defaults to "https://api.fhirfly.io/oauth2/token"
});

// The SDK automatically exchanges credentials, caches the token,
// refreshes before expiry, and retries on rejection
const ndc = await client.ndc.lookup("0069-0151-01");
console.log(ndc.data.brand_name);

Creating a Secure Credential

1. Go to Dashboard → Credentials
2. Click Create Credential
3. Select Secure (OAuth2)
4. Choose your scopes
5. Copy your client_id and client_secret (secret shown only once!)

Token Lifetime

• Access tokens expire after 10 minutes
• The SDK automatically refreshes tokens before expiry
• No refresh tokens — use the client credentials grant again

Next Steps

• Scopes — Control what data your credentials can access
• Security — Security model and best practices
• MCP Integration — Connect FHIRfly to AI assistants like Claude