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

# Authentication

> How to authenticate your API requests

# Authentication

SwiftPay uses API keys to authenticate requests. You can view and manage your API keys in the [Dashboard](https://app.swiftpay.cx/settings/api-keys).

## API Keys

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

### Key Format

All API keys follow this format:

```
mp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

* `mp_` - Prefix identifying SwiftPay keys
* `live_` - Environment indicator (all keys are live)
* `xxxxxxxx...` - Unique key identifier

## Authentication Header

Authentication to the API is performed via the `Authorization` header with the `Bearer` scheme:

```bash theme={null}
Authorization: Bearer mp_live_your_api_key
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.swiftpay.cx/api/balance \
    -H "Authorization: Bearer mp_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.swiftpay.cx/api/balance", {
     headers: {
        Authorization: "Bearer mp_live_your_api_key",
     },
  });
  ```

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

  response = requests.get(
      'https://api.swiftpay.cx/api/balance',
      headers={'Authorization': 'Bearer mp_live_your_api_key'}
  )
  ```

  ```php PHP theme={null}
  $ch = curl_init('https://api.swiftpay.cx/api/balance');
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer mp_live_your_api_key'
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = curl_exec($ch);
  ```
</CodeGroup>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Store keys securely" icon="lock">
    Store your API keys in environment variables or a secure secrets manager.
    Never hardcode them in your application. `bash # .env file
              SWIFTPAY_API_KEY=mp_live_your_api_key `
  </Accordion>

  {" "}

  <Accordion title="Use server-side only" icon="server">
    API keys should only be used in server-side code. Never expose them in
    client-side JavaScript, mobile apps, or browser extensions.
  </Accordion>

  {" "}

  <Accordion title="Rotate keys regularly" icon="rotate">
    Rotate your API keys periodically and immediately if you suspect they've been
    compromised. You can create new keys in the dashboard.
  </Accordion>

  <Accordion title="Use separate keys per environment" icon="code-branch">
    If you have staging and production environments, use separate API keys for
    each to isolate any issues.
  </Accordion>
</AccordionGroup>

## Authentication Errors

| Error Code | Description                               |
| ---------- | ----------------------------------------- |
| `401`      | No API key provided or invalid key format |
| `403`      | Valid key but insufficient permissions    |

<ResponseExample>
  ```json 401 Response theme={null}
  {
    "success": false,
    "error": {
      "type": "unauthenticated",
      "message": "Invalid API key provided",
      "requestId": "req_abc123"
    }
  }
  ```
</ResponseExample>

## Session Authentication

In addition to API keys, SwiftPay also supports session-based authentication for dashboard access. This is used automatically when you're logged into the dashboard.

<Note>
  API keys are the recommended authentication method for programmatic access.
  Session authentication is only used for the web dashboard.
</Note>