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

# Authenticate with the Accelebit Payments API

> Learn how to get and use Accelebit API keys, authenticate every request with the X-API-Key header, rotate keys safely, and handle rate limits.

Every request to the Accelebit API must be authenticated with a secret API key. Keys are scoped to your merchant account and to a specific mode — test or live — so you can build and test integrations without touching real payment infrastructure. This page covers key types, how to use them, how to manage them safely, and the rate limits that apply to each mode.

## API key types

Accelebit issues three key types per merchant account:

| Key type          | Prefix           | Purpose                                                                           |
| ----------------- | ---------------- | --------------------------------------------------------------------------------- |
| Secret key (test) | `smtgw_sk_test_` | Test mode. No real charges are made. Use for development and staging.             |
| Secret key (live) | `smtgw_sk_live_` | Live mode. Processes real payments against upstream providers.                    |
| Public key        | `smtgw_pk_`      | Identifies your account in client-side contexts. Not used for API authentication. |

All API requests require a **secret key**. The public key is not accepted as authentication.

## Authenticating requests

Include your secret key in the `X-API-Key` header on every request:

```bash theme={null}
curl https://api.gateway.accelebit.com/v1/payments \
  -H "X-API-Key: smtgw_sk_test_your_secret_key"
```

If the key is missing, invalid, or revoked, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "data": null,
  "error": {
    "status": 401,
    "name": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

## Key management

Manage your API keys from the [Dashboard](https://dashboard.accelebit.com/dashboard/developers/api-keys):

* **View keys** — Secret keys are shown once at creation. Store them securely immediately; you cannot retrieve them again.
* **Rotate keys** — Generate a new key and revoke the old one. Both keys remain valid during a grace period so you can update your integration without downtime.
* **Revoke keys** — Immediately disable a compromised key. Any in-flight requests using that key will be rejected.

## Security best practices

<Warning>
  Your secret key grants full access to your merchant account. Treat it like a password.
</Warning>

* **Never expose your secret key in client-side code**, Git repositories, or application logs.
* **Use environment variables** to inject keys into your application at runtime — for example, store the key as `ACCELEBIT_SECRET_KEY` and read it from `process.env` or your secrets manager.
* **Restrict access** within your team. Only backend engineers should have access to live secret keys.
* **Rotate keys periodically** and immediately if you suspect a compromise.
* **Use test keys** (`smtgw_sk_test_`) in development and staging. Test keys cannot process real payments.

## Idempotency

All `POST` endpoints require an `Idempotency-Key` header. This guarantees that retrying a failed or timed-out request will not create a duplicate transaction.

```bash theme={null}
curl -X POST https://api.gateway.accelebit.com/v1/payments \
  -H "X-API-Key: smtgw_sk_test_your_secret_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

<Tip>
  Use a UUID generated per request as your idempotency key — for example, `pay_$(uuidgen)` in bash or `crypto.randomUUID()` in Node.js.
</Tip>

Key behavior to keep in mind:

* If you retry a request with the same idempotency key, the API returns the original response without reprocessing the payment.
* Idempotency keys expire after **24 hours**. After expiry, the same key can be reused for a new request.

## Merchant scoping

All resources — payments, refunds, and customers — are automatically scoped to the merchant account associated with the API key you use. You cannot read or modify another merchant's data, regardless of the key permissions.

## Rate limits

The API enforces rate limits per API key:

| Mode      | Limit                   |
| --------- | ----------------------- |
| Test mode | 100 requests / minute   |
| Live mode | 1,000 requests / minute |

When you exceed the limit, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying. Implement exponential backoff in your integration to handle this gracefully.