> ## Documentation Index
> Fetch the complete documentation index at: https://ixoworld-mintlify-9a7944b6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Choose and implement the correct authentication pattern for each IXO API surface.

This guide helps you pick an auth strategy by surface. It does not define canonical headers, endpoint literals, or environment values.

## Before you start

* Identify which interface you are integrating with: protocol gateway or service API.
* Confirm active endpoint and network from `/reference/networks-and-endpoints`.
* Confirm required credential format from `/reference/authentication-matrix`.

## What this guide does

You will map your integration to an auth pattern, apply the required header format, and verify a successful authenticated request without guessing cross-surface behavior.

## Step 1 - Classify the target surface

* Protocol gateways: `/api-reference/rpc-api`, `/api-reference/grpc-gateway-api`
* Service APIs: `/api-reference/blocksync-graphql-api`, `/api-reference/matrix-state-bot-api`, `/api-reference/registry-api`

## Step 2 - Apply the required auth format

Common formats used across IXO surfaces are documented in `/reference/authentication-matrix`.

<Warning>
  Do not reuse one format across all APIs unless the authentication matrix explicitly confirms it.
</Warning>

## Step 3 - Verify the result

Send a minimal authenticated read request to the target interface.

Expected result:

* HTTP success response for your target endpoint.
* No authentication or permission error.

## Troubleshooting

### `401 Unauthorized`

Your credential format or token source does not match the target API surface. Re-check `/reference/authentication-matrix`.

### `403 Forbidden`

Your identity is valid but missing required scope or role for the resource.

### `429 Too Many Requests`

The surface-level rate policy has been exceeded. Apply retry/backoff per API guidance.

## Next steps

<CardGroup cols={3}>
  <Card title="API authentication reference" icon="key" href="/api-reference/authentication">
    Apply endpoint-specific authentication requirements and headers.
  </Card>

  <Card title="Networks and endpoints" icon="network-wired" href="/reference/networks-and-endpoints">
    Select chain IDs and base URLs for your environment.
  </Card>

  <Card title="Product and SDK map" icon="diagram-project" href="/reference/product-and-sdk-map">
    Confirm canonical product names, SDK names, and routes.
  </Card>
</CardGroup>