> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leapfinancial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Secure your API requests with API keys and configure webhook verification

## API Keys

All requests to the M2M Partner API require authentication using an API key. You can manage your API keys in the [Partner Portal](https://partner.m2m.leapfinancial.com).

### Key format

API keys follow a specific format that indicates the environment:

| Prefix      | Environment | Example                                     |
| ----------- | ----------- | ------------------------------------------- |
| `m2m_test_` | Sandbox     | `m2m_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |
| `m2m_live_` | Production  | `m2m_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` |

<Warning>
  API keys are shown only once when created. Store them securely - you cannot retrieve the full key later.
</Warning>

### Using your API key

Include your API key in the `X-API-Key` header for all requests:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://m2m-backend-qa.up.railway.app/partner/links \
    -H "X-API-Key: m2m_test_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{"referenceId": "user_123"}'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://m2m-backend-qa.up.railway.app/partner/links', {
    method: 'POST',
    headers: {
      'X-API-Key': 'm2m_test_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ referenceId: 'user_123' })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://m2m-backend-qa.up.railway.app/partner/links',
      headers={
          'X-API-Key': 'm2m_test_your_api_key_here',
          'Content-Type': 'application/json'
      },
      json={'referenceId': 'user_123'}
  )
  ```
</CodeGroup>

### Managing API keys

From the Partner Portal, you can:

* **Create new keys** - Generate additional keys for different services or environments
* **Revoke keys** - Immediately invalidate a compromised key
* **View key prefixes** - See which keys are active (full keys are never shown again)
* **Track usage** - Monitor when each key was last used

<Tip>
  Create separate API keys for different services or environments. This makes it easier to rotate keys without disrupting all integrations.
</Tip>

## Authentication errors

When authentication fails, you'll receive one of these error responses:

### Missing API key

```json theme={null}
{
  "code": "UNAUTHORIZED",
  "message": "Missing authentication. Provide X-API-Key or Bearer token."
}
```

### Invalid or revoked key

```json theme={null}
{
  "code": "INVALID_API_KEY",
  "message": "Invalid or revoked API key"
}
```

### Suspended partner

```json theme={null}
{
  "code": "PARTNER_SUSPENDED",
  "message": "Partner account is suspended or not found"
}
```

## Webhook authentication

When M2M sends webhooks to your endpoint, each request includes a signature so you can verify it came from M2M.

### Webhook headers

Every webhook includes these headers:

| Header            | Description                                    |
| ----------------- | ---------------------------------------------- |
| `X-M2M-Signature` | HMAC-SHA256 signature (format: `sha256=<hex>`) |
| `X-M2M-Timestamp` | Unix timestamp when the webhook was sent       |
| `X-M2M-Event`     | Event type (e.g., `link.opened`)               |

### Webhook secret

Your webhook secret is available in the Partner Portal under webhook settings. The secret format is:

```
whsec_<48_hex_characters>
```

<Warning>
  Keep your webhook secret secure. If compromised, regenerate it immediately in the Partner Portal.
</Warning>

### Verifying signatures

See the [Webhook Security](/m2m/webhooks/security) guide for complete verification examples in multiple languages.

## Security best practices

<AccordionGroup>
  <Accordion title="Store keys securely">
    * Never commit API keys to version control
    * Use environment variables or a secrets manager
    * Restrict access to keys on a need-to-know basis
  </Accordion>

  <Accordion title="Use environment-appropriate keys">
    * Use `m2m_test_*` keys in development and staging
    * Use `m2m_live_*` keys only in production
    * Never use production keys for testing
  </Accordion>

  <Accordion title="Rotate keys regularly">
    * Create a new key before revoking the old one
    * Update your services to use the new key
    * Revoke the old key once migration is complete
  </Accordion>

  <Accordion title="Monitor for anomalies">
    * Track API usage patterns
    * Set up alerts for unusual activity
    * Review webhook delivery logs regularly
  </Accordion>

  <Accordion title="Verify webhook signatures">
    * Always verify the `X-M2M-Signature` header
    * Check the timestamp to prevent replay attacks
    * Reject webhooks with invalid signatures
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/m2m/quickstart">
    Create your first magic link.
  </Card>

  <Card title="Webhook Security" icon="shield" href="/m2m/webhooks/security">
    Implement signature verification.
  </Card>
</CardGroup>