API Key Management

Create, list, and manage hospital-scoped API keys

API Key Lifecycle

From creation to rotation

The backend allows multiple active API keys per hospital. Recommended pattern: separate keys by integration or use case and by permission scope, rather than sharing one key everywhere.

Create

Admin generates a new API key with specific permissions

Save Securely

Store secret in secure vault (only shown once)

Use in Integration

Include key, secret, and token in API requests

Disable/Rotate

Periodically rotate keys and disable old ones

Endpoints

POSThttps://server.nyraai.io/api/hospitals/:hospitalId/api-keys

Create a new API key with specified permissions

Permission: SUPER_ADMIN or HOSPITAL_ADMIN

Headers

Authorizationrequired

Admin Bearer token

Content-Typerequired

application/json

Request Body

{
  "permissions": [
    "patients:create",
    "patients:read",
    "appointments:write",
    "appointments:read",
    "calls:read",
    "ws:ticket",
    "analytics:read"
  ]
}

Response

{
  "success": true,
  "data": {
    "key": "nyra_2f9a...",
    "secret": "aVeryLongBase64Secret...",
    "token": "a1b2c3d4e5f6789abcdef...",
    "id": "api-key-uuid",
    "permissions": ["patients:read", "patients:create"]
  },
  "message": "New API key and token generated successfully."
}

GEThttps://server.nyraai.io/api/hospitals/:hospitalId/api-keys

List all API keys for a hospital

Permission: SUPER_ADMIN or HOSPITAL_ADMIN

Headers

Authorizationrequired

Admin Bearer token

Response

{
  "success": true,
  "data": [
    {
      "id": 12,
      "key": "nyra_2f9a...",
      "is_active": true,
      "branch_id": null,
      "permissions": ["patients:read", "appointments:write"],
      "created_at": "2026-04-07T11:00:00+05:30",
      "updated_at": "2026-04-07T11:00:00+05:30"
    },
    {
      "id": 13,
      "key": "nyra_3b4c...",
      "is_active": false,
      "branch_id": "branch-uuid",
      "permissions": ["patients:read"],
      "created_at": "2026-04-01T10:00:00+05:30",
      "updated_at": "2026-04-06T15:30:00+05:30"
    }
  ]
}

PATCHhttps://server.nyraai.io/api/hospitals/:hospitalId/api-keys/:apiKeyId

Enable or disable an API key. The :apiKeyId path segment may be the numeric database id (e.g. 32) or the full key string (e.g. nyra_abc...).

Permission: SUPER_ADMIN or HOSPITAL_ADMIN

Headers

Authorizationrequired

Admin Bearer token

Content-Typerequired

application/json

Request Body

{
  "is_active": false
}

Response

{
  "success": true,
  "data": {
    "id": 12,
    "key": "nyra_2f9a...",
    "is_active": false
  }
}

DELETEhttps://server.nyraai.io/api/hospitals/:hospitalId/api-keys/:apiKeyId

Delete an API key. The :apiKeyId path segment may be the numeric database id or the full key string (same as PATCH).

Permission: SUPER_ADMIN or HOSPITAL_ADMIN

Headers

Authorizationrequired

Admin Bearer token

Response

{
  "success": true,
  "message": "API key deleted successfully"
}

Rate Limits & Key Management

Important restrictions and best practices

⚡ Rate Limiting

Each external API key is limited to 12 requests per second and 60 requests per minute. Exceeding either limit returns 429 (Too Many Requests).

• Minute window resets every 60 seconds
• Rate limit applies per API key, not per hospital
• Create separate keys for high-traffic integrations

🔑 Update and delete by id or key

PATCH and DELETE on /api/hospitals/:id/api-keys/:apiKeyId accept either the numeric row id (for example 32) or the full public key string (for example nyra_...). Use whichever your dashboard or client already has.

• Disabling a key stops it from making external API requests
• Rotating keys: create a new key, migrate clients, then disable or delete the old key

📋 How to Manage Keys

View Keys: Dashboard → API Keys → See all active and inactive keys
Disable: Click the disable button next to the key you want to retire
Create New: Click "Create API Key" → Select permissions → Copy credentials
Verify: Test new key before removing old one from your application

Permission Types

Available permissions for API keys

patients:create

Create new patients

patients:read

Read patient data

appointments:write

Create and modify appointments

appointments:read

Read appointment data

calls:read

Read call records

ws:ticket

Generate WebSocket connections

analytics:read

Read usage analytics

Best Practices

✓ Create separate API keys for different integrations
✓ Grant minimum necessary permissions per key
✓ Store secrets in environment variables or vaults
✓ Rotate keys regularly (recommended: every 90 days)
✓ Immediately disable compromised keys
✓ Monitor API key usage in analytics
✓ Use branch-scoped keys when applicable for multi-branch hospitals