API Keys

API keys let you make server-to-server calls to the Notify API without using user authentication tokens. They're ideal for backend services that send push notifications.

What This Is

An API key is a long-lived credential tied to a specific tenant. Unlike user tokens that expire, API keys remain valid until deleted. They can only access the tenant they were created for.

When to Use

• Your backend server sends push notifications
• You don't want to manage token refresh in your server
• You need a stable credential for automated systems

Creating an API Key

CLI

mushu tenant api-key TENANT_ID --name "backend-server"

Or using the default tenant:

mushu tenant api-key --name "backend-server"

API

POST /tenants/{tenant_id}/api-keys
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "backend-server"
}

Response:

{
  "key_id": "key_abc123",
  "key": "msk_live_xxxxxxxxxxxxxxxxxxxx",
  "name": "backend-server",
  "created_at": "2024-01-15T10:30:00Z"
}

Using API Keys

Include the key in the X-API-Key header:

POST /tenants/{tenant_id}/notify
X-API-Key: msk_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "user_id": "user-123",
  "alert": {
    "title": "Hello",
    "body": "From your server"
  }
}

Example: Node.js

async function sendPush(userId, title, body) {
  const response = await fetch(`https://notify.mushucorp.com/tenants/${TENANT_ID}/notify`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.MUSHU_API_KEY,
    },
    body: JSON.stringify({
      user_id: userId,
      alert: { title, body },
    }),
  });

  return response.json();
}

Example: Python (SDK)

import os
import mushu
from mushu.notify.api.push import send_notification
from mushu.notify.models import SendNotificationRequest, Alert

client = mushu.client("notify", api_key=os.environ["MUSHU_API_KEY"])

def send_push(tenant_id: str, user_id: str, title: str, body: str):
    response = send_notification.sync_detailed(
        tenant_id=tenant_id,
        client=client,
        body=SendNotificationRequest(
            user_id=user_id,
            alert=Alert(title=title, body=body),
        ),
    )
    return response.parsed

Install: pip install mushu

API Key Permissions

API keys can perform these operations on their tenant:

• Register and unregister devices
• List devices for a user
• Send notifications (single and bulk)

API keys cannot:

• Create, modify, or delete the tenant
• Create or delete other API keys
• Access other tenants

Key Naming

Give keys descriptive names so you know their purpose later. Examples:

• backend-server
• ios-app-production
• notification-service
• cron-job-reminders

Security Best Practices

1. Use environment variables - Never hardcode keys in source code
2. Rotate periodically - Create new keys and delete old ones
3. One key per service - If a key is compromised, you only need to rotate that one
4. Monitor usage - Watch for unusual activity patterns

Deleting API Keys

If a key is compromised or no longer needed, delete it immediately. Any requests using that key will fail afterward.

DELETE /tenants/{tenant_id}/api-keys/{key_id}
Authorization: Bearer YOUR_TOKEN

FAQ

Do API keys expire?

No. API keys remain valid until you delete them. This is intentional for server-to-server use cases where token refresh is impractical.

Can I see my key again after creating it?

No. The full key is only shown once. If you lose it, delete the key and create a new one.

How many keys can I create?

There's no hard limit. Create as many as you need for different services and environments.

Should I use API keys in my iOS app?

Yes, for device registration. The iOS app needs to register device tokens, and an API key is simpler than managing user tokens for this purpose. Just be aware that API keys in shipped apps can be extracted.