Authentication and API Keys

How API keys work

SOAPNoteAPI uses API keys to authenticate requests. Every key starts with snapi_sk_ and is tied to your customer account. The full key is shown exactly once at creation time and cannot be retrieved again -- SOAPNoteAPI stores only a SHA-256 hash. If you lose a key, revoke it and create a new one.

Creating an API key

You can create API keys from the SOAPNoteAPI dashboard (Settings > API Keys) or programmatically via the Dashboard API. Each account can have up to 5 active keys.

Dashboard UI

• Sign in to app.soapnoteapi.com.
• Navigate to Settings > API Keys.
• Click "Create API Key" and enter a descriptive name (e.g., "production-server", "staging-backend").
• Copy the full key (snapi_sk_...) immediately. It will not be displayed again.

Programmatic creation (Dashboard API)

The Dashboard API requires session JWT authentication (not an API key). Use this from admin tools or internal dashboards that already have a user session.

curl -X POST https://api.soapnoteapi.com/dashboard/customers/{customer_id}/api-keys \
  -H "Authorization: Bearer SESSION_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "production-server" }'

Response

{
  "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "production-server",
  "key_prefix": "snapi_sk",
  "key": "snapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "status": "active",
  "created_at": "2026-03-18T10:00:00.000Z"
}

Using your API key

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

curl -X POST https://api.soapnoteapi.com/v1/note \
  -H "Authorization: Bearer snapi_sk_live_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{ "transcript": "...", "specialty": "nurse_practitioner" }'

Listing and identifying keys

List all keys for your account to see which are active, when they were created, and when they were last used. The last_used_at field helps identify stale keys that should be revoked.

curl https://api.soapnoteapi.com/dashboard/customers/{customer_id}/api-keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

{
  "items": [
    {
      "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "production-server",
      "key_prefix": "snapi_sk",
      "status": "active",
      "created_at": "2026-03-18T10:00:00.000Z",
      "last_used_at": "2026-03-18T14:22:00.000Z"
    },
    {
      "key_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "staging-backend",
      "key_prefix": "snapi_sk",
      "status": "active",
      "created_at": "2026-03-15T09:00:00.000Z",
      "last_used_at": null
    }
  ]
}

Revoking a key

Revoke a key immediately when it is compromised, no longer needed, or being rotated. Revoked keys are rejected instantly on the next API call.

curl -X DELETE https://api.soapnoteapi.com/dashboard/customers/{customer_id}/api-keys/{key_id} \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

Key rotation best practices

Rotate your API keys periodically (every 90 days is a common baseline) and immediately if a key may have been exposed. Use a zero-downtime rotation pattern:

• Step 1: Create a new API key in the dashboard.
• Step 2: Update your application configuration or secrets manager with the new key.
• Step 3: Deploy the change and verify requests succeed with the new key.
• Step 4: Revoke the old key once all services have switched over.

Security best practices

• Never commit API keys to version control. Use .env files (added to .gitignore) or a secrets manager like AWS Secrets Manager, HashiCorp Vault, or Doppler.
• Never expose API keys in client-side code. API calls should be made from your backend server. A key embedded in JavaScript or a mobile app binary can be extracted by anyone.
• Use separate keys for each environment. Create distinct keys named "production", "staging", and "development" so a compromised dev key cannot access production data.
• Monitor last_used_at. Keys that have not been used in 90+ days may be forgotten credentials. Revoke them.
• Set up alerts for 401 errors. A spike in authentication failures may indicate a leaked key being tested by an unauthorized party.

Environment variable examples

.env file

# .env (add to .gitignore)
SOAPNOTEAPI_KEY=snapi_sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Node.js

const apiKey = process.env.SOAPNOTEAPI_KEY;

const response = await fetch("https://api.soapnoteapi.com/v1/note", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ transcript: "...", specialty: "physician" }),
});

Python

import os
import requests

api_key = os.environ["SOAPNOTEAPI_KEY"]

response = requests.post(
    "https://api.soapnoteapi.com/v1/note",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={"transcript": "...", "specialty": "physician"},
)

Limits

• Maximum 5 active API keys per account.
• Revoked keys do not count toward the limit.
• There is no separate "test" vs. "live" key distinction -- all keys have the same access level. Use separate accounts or named keys to distinguish environments.