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

# Authentication

Subotiz OpenAPI uses **API Keys** to authenticate requests. Every API call must include a valid API Key in the HTTP request header. The gateway validates the key before forwarding the request to backend services.

## Get Your API Key

Log in to the Subotiz merchant dashboard and navigate to **Settings > Developer Settings** to view and manage your API Keys.

<Warning>
  Your API Key is shown in full only once at creation time. Store it securely. If lost, you will need to generate a new one — the old key will be immediately invalidated.
</Warning>

<Frame>
  <img src="https://mintcdn.com/shoplazza-92a3a725/kRg57qaFxQCCAN8Z/images/8346e310-f6506c2bdf2eb946aaad06d8e371323e3ae9803ce16d7e8664a04083-image.png?fit=max&auto=format&n=kRg57qaFxQCCAN8Z&q=85&s=2c144067cbcfe9df97d6db110b7edcb3" width="1916" height="715" data-path="images/8346e310-f6506c2bdf2eb946aaad06d8e371323e3ae9803ce16d7e8664a04083-image.png" />
</Frame>

## Making Authenticated Requests

### Request Header Format

All OpenAPI requests must include the following HTTP header:

| Header          | Value                   | Description                                       |
| --------------- | ----------------------- | ------------------------------------------------- |
| `Authorization` | `Bearer {your_api_key}` | Replace `{your_api_key}` with your actual API Key |

### Example

```bash theme={null}
curl -X GET "https://api.subotiz.com/openapi/v1/orders" \
  -H "Authorization: Bearer {your_api_key}"
```

## Key Rotation

When a key is compromised or needs periodic renewal, you can **rotate** it from the Developer Settings page.

### Rotation Process

1. Initiate key rotation in Developer Settings — a new API Key will be generated
2. The system sets a grace period for the old key (default: 3 minutes, customizable at rotation time)
3. During the grace period, **both old and new keys are valid** — update your services to use the new key as soon as possible
4. After the grace period ends, the old key is automatically invalidated; only the new key remains valid

<Warning>
  Complete the switch to the new key before the grace period ends to avoid request interruptions. If you have Webhooks configured, key rotation also affects Webhook signature verification — it is recommended to support both old and new keys for signature validation during the grace period. See [Webhook Introduction](/en/webhook/introduction-2) for details.
</Warning>

## Error Handling

When authentication fails, the API returns an HTTP `401` status code. The following table lists common error causes and recommended actions:

| Error Cause                      | What to Do                                                                |
| -------------------------------- | ------------------------------------------------------------------------- |
| Missing `Authorization` header   | Ensure your request includes `Authorization: Bearer {key}`                |
| Invalid or non-existent API Key  | Verify the key is correct, or retrieve it again from the dashboard        |
| API Key expired or revoked       | Generate a new key from Developer Settings                                |
| Malformed `Authorization` header | Ensure the format is `Bearer {key}` with exactly one space after `Bearer` |

### Error response example

```json theme={null}
{
  "code": "unauthorizedError",
  "message": "ApiKey authentication is required"
}
```