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

# Authentication

> Pass your API key in the x-api-key header or exchange it for a short-lived JWT token. Learn both authentication methods and how to obtain your credentials.

Every request to the Axra Pay API must be authenticated. Axra supports two methods: passing your API key directly in a request header, or exchanging your key and secret for a short-lived JWT token. Both methods work for all endpoints — choose the one that fits your architecture.

## Method 1: API key header

The simplest way to authenticate is to include your API key in the `x-api-key` header on every request. This approach works well for server-side integrations where your API key is stored securely in an environment variable.

```bash theme={null}
x-api-key: bk_live_abc123...
```

**Example request:**

```bash theme={null}
curl -X POST https://api.useaxra.com/api/v1/business/checkout/session \
  -H "x-api-key: bk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "customerEmail": "customer@example.com",
    "successUrl": "https://yoursite.com/success"
  }'
```

<Warning>
  Never expose your API key in client-side code, public repositories, or frontend JavaScript. Always make Axra Pay API calls from your server.
</Warning>

***

## Method 2: JWT token exchange

For integrations that prefer short-lived credentials, you can exchange your `apiKey` and `apiSecret` for a JWT bearer token. The token expires after one hour and must be refreshed before it does.

<Note>
  Your `webhookSecret` doubles as your `apiSecret` for token authentication. They are the same credential.
</Note>

### Step 1: Request a token

Send a `POST` request to `/business/auth/token` with your `apiKey` and `apiSecret` in the request body.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.useaxra.com/api/v1/business/auth/token \
    -H "Content-Type: application/json" \
    -d '{
      "apiKey": "bk_live_abc123...",
      "apiSecret": "bs_live_xyz789..."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.useaxra.com/api/v1/business/auth/token',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        apiKey: 'bk_live_abc123...',
        apiSecret: 'bs_live_xyz789...',
      }),
    }
  );

  const { accessToken, expiresIn } = await response.json();
  ```
</CodeGroup>

**Request body parameters:**

<ParamField body="apiKey" type="string" required>
  Your business API key. Starts with `bk_live_` for production or `bk_test_` for sandbox.
</ParamField>

<ParamField body="apiSecret" type="string" required>
  Your API secret. This is the same value as your `webhookSecret`.
</ParamField>

### Step 2: Read the response

A successful request returns the following fields:

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "businessId": "biz_01H...",
  "businessName": "Acme Corp"
}
```

<ResponseField name="accessToken" type="string" required>
  The JWT token to include in subsequent requests.
</ResponseField>

<ResponseField name="tokenType" type="string" required>
  Always `"Bearer"`. Use this as the prefix in your `Authorization` header.
</ResponseField>

<ResponseField name="expiresIn" type="number" required>
  Token lifetime in seconds. Always `3600` (one hour).
</ResponseField>

<ResponseField name="businessId" type="string">
  The unique identifier for your business profile.
</ResponseField>

<ResponseField name="businessName" type="string">
  Your registered business name.
</ResponseField>

### Step 3: Use the token

Include the `accessToken` in the `Authorization` header of every subsequent request:

```bash theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

**Example authenticated request:**

```bash theme={null}
curl -X GET https://api.useaxra.com/api/v1/business/payments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```

<Tip>
  Refresh your token before it expires by calling `POST /business/auth/token` again with the same credentials. Build a refresh mechanism into your application rather than handling 401 errors reactively.
</Tip>

### Token error responses

| HTTP status        | Meaning                                              |
| ------------------ | ---------------------------------------------------- |
| `401 Unauthorized` | The `apiKey` or `apiSecret` is invalid.              |
| `400 Bad Request`  | The request body is missing `apiKey` or `apiSecret`. |

***

## Getting your credentials

<Steps>
  <Step title="Create an account">
    [Register at the Axra dashboard](https://app.useaxra.com/register) to create a business profile and generate your API credentials.
  </Step>

  <Step title="Copy your credentials immediately">
    Your `apiKey` (format: `bk_live_...`) and `webhookSecret` are shown **only once** when your account is created. Copy both values to a secure password manager or secrets vault before leaving the page.
  </Step>

  <Step title="Store credentials securely">
    Never hard-code credentials in your source code. Store them as environment variables or in a secrets management service such as AWS Secrets Manager, HashiCorp Vault, or your hosting provider's secret store.
  </Step>

  <Step title="Regenerate a lost API key">
    If you lose your API key, call `POST /business/regenerate-api-key` to issue a new one. Your previous key is immediately invalidated — update any running services before regenerating.

    ```bash theme={null}
    curl -X POST https://api.useaxra.com/api/v1/business/regenerate-api-key \
      -H "x-api-key: bk_live_your_current_key"
    ```
  </Step>
</Steps>

<Note>
  Axra stores API keys as SHA-256 hashes. Your raw key is never stored on Axra's servers, which is why it cannot be retrieved after creation — only regenerated.
</Note>

***

## Choosing an authentication method

|                      | API key header                                    | JWT token                                          |
| -------------------- | ------------------------------------------------- | -------------------------------------------------- |
| **Setup complexity** | Minimal                                           | Requires token exchange and refresh logic          |
| **Best for**         | Server-side integrations, scripts, internal tools | Architectures that require short-lived credentials |
| **Token lifetime**   | Long-lived (until regenerated)                    | 1 hour                                             |
| **Revocation**       | Regenerate key to invalidate                      | Tokens expire automatically                        |

For most server-side integrations, the API key header is the simplest and most practical choice. Use JWT tokens if your security policy requires credentials that expire automatically.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Payments" icon="credit-card" href="/payments/overview">
    Start accepting payments with server-to-server card charging.
  </Card>

  <Card title="Checkout Sessions" icon="store" href="/payments/checkout-sessions">
    Use a hosted payment page to accept payments without handling card data.
  </Card>
</CardGroup>