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
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.
Next steps
- API authentication reference:
/api-reference/authentication
- Networks and endpoints:
/reference/networks-and-endpoints
- Product and SDK map:
/reference/product-and-sdk-map
