# Authentication

The API uses issuer server-side API tokens and source IP allowlisting. Use the API-token header shown in these docs and in the API reference.

## Network Access

The Percents API is behind a firewall that allowlists inbound source IPs. To access the API, the issuer must provide the source IP addresses or CIDR ranges that will call Percents from issuer-controlled infrastructure.

Keep the allowlist aligned with production and sandbox egress changes. Requests from unregistered source IPs should be expected to fail before API-token authentication is evaluated.

## API Tokens

Send the token in the `Authorization` header:

```http
Authorization: token <tok_id>:<api_secret>
```

Example:

```http
Authorization: token tok_11111111-1111-4111-8111-111111111111:api_test_secret
```

The `tok_` value identifies the token. The `api_` prefix may appear in token-management ids where relevant to the integration or support workflow. Treat the token secret as confidential and never place it in client-side applications.

## SDK Request Routing

The SDK does not use an issuer API token in the browser. It uses a customer-side proxy and a short-lived token restricted to one cardholder group. See [SDK Authentication](/percents-api/auth-security/sdk-auth) for the session and production-authentication model.

The issuer API-token scheme on this page remains for issuer server-to-server API calls. Do not use those credentials in the SDK, iframe, or a browser-accessible proxy response.

## Failure Modes

Authentication and authorization failures use the standard public error response:

```json
{
  "uuid": "err_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "code": 401001,
  "httpStatusCode": 401,
  "message": "Unauthorized"
}
```

Use the `uuid` when contacting Percents support. Do not branch production behavior on the human-readable `message`.