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.
Do not reuse one format across all APIs unless the authentication matrix explicitly confirms it.
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.