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

# Authentication

> How to authenticate with the Bolta API and use request headers.

<Note>
  Some links point to the service guide, which is in Korean.
</Note>

## API key authentication (Basic Auth)

The Bolta API uses HTTP Basic Authentication. Base64-encode your API key and include it in the `Authorization` header.

```bash theme={"dark"}
Authorization: Basic {Base64(API_KEY:)}
```

<Warning>
  Append a colon (`:`) to the API key before Base64-encoding it.
</Warning>

**Example**

```bash theme={"dark"}
# When the API key is test_abc123
# Base64("test_abc123:") = dGVzdF9hYmMxMjM6

curl -X POST https://xapi.bolta.io/v1/taxInvoices/issue \
  -H "Authorization: Basic dGVzdF9hYmMxMjM6" \
  -H "Content-Type: application/json"
```

## Test key vs. live key

| Type     | Prefix  | Purpose                                                              |
| -------- | ------- | -------------------------------------------------------------------- |
| Test key | `test_` | Sandbox environment, not connected to the National Tax Service (NTS) |
| Live key | `live_` | Production environment, connected to the NTS                         |

Use a test key for development and testing.

> For how to issue an API key, see the [API key guide](/docs/developer-center/api-key).

## Request headers

### Client-Reference-Id

`Bolta-Client-Reference-Id` identifies an issuance request. Tax invoices, cash receipts, and document issuance handle duplicate requests differently.

#### Tax invoices

You can optionally send a non-blank value between 1 and 255 characters with standard issuance, amendment, and reverse issuance requests.

```bash theme={"dark"}
Bolta-Client-Reference-Id: your-unique-reference-id
```

After a value is used with an API key, that API key cannot reuse it for another tax invoice request, regardless of the request content or endpoint. A duplicate request returns HTTP `400` with `INVALID_REQUEST`.

If you do not receive a response because of a network error, do not resend the request. Pass the value as `clientReferenceId` to retrieve the processing status.

```bash theme={"dark"}
curl "https://xapi.bolta.io/v1/taxInvoices/issue/status?clientReferenceId=your-unique-reference-id" \
  -H "Authorization: Basic {apiKey}"
```

#### Cash receipts

Cash receipt issuance and cancellation requests require a value between 1 and 255 characters. If the same API key retries with the same client reference ID, request content, and request type, the API returns `202 Accepted` with the existing request's `issuanceKey`. If the request content or type differs, the API returns `409 Conflict` with `IDEMPOTENCY_CONFLICT`.

Use a different value for a cancellation request than for its issuance request. See the [Cash receipt guide](/en/docs/api-introduction/cash-receipt-guide) for the full request flow.

#### Document issuance

Document issuance requests require a value between 1 and 255 characters. If you resend the same value with the same body, the API returns the existing request. If the body differs, the API returns `409 Conflict` with `IDEMPOTENCY_CONFLICT`. See [Document Issuance](/en/docs/api-introduction/document-issuance) for the full flow.