# Authentication
Source: https://docs.ixo.world/api-reference/authentication
Authentication patterns used across IXO Protocol and IXO service APIs.
Use this page to understand auth surface area by API family. For canonical literals (headers, token sources, environment-specific behavior), use the authentication matrix.
## Scope
* This page summarizes auth methods by API surface.
* It does not define a single universal flow for all IXO APIs.
* Protocol docs and service docs can require different credentials.
## Common request patterns
Common header formats used across IXO docs are centralized in `/reference/authentication-matrix`.
Do not assume any one header or token type applies to every endpoint. Confirm each interface against `/reference/authentication-matrix`.
## API families and auth responsibility
* **Surfaces:** `/api-reference/rpc-api`, `/api-reference/grpc-gateway-api`
* **Auth notes:** Chain and node access patterns vary by network and deployment.
* **Surfaces:** `/api-reference/blocksync-graphql-api`, `/api-reference/matrix-state-bot-api`, `/api-reference/registry-api`
* **Auth notes:** Service operators can enforce different credentials and scopes.
## Security baseline
* Use HTTPS for all authenticated requests.
* Keep credentials in secure runtime storage, not source files.
* Rotate tokens and keys according to your operator policy.
* Log request identifiers and auth failures for incident triage.
## Source-of-truth references
Use canonical auth literals and requirements by interface.
Confirm network-specific endpoint mappings before integration.
Navigate IXO products, APIs, and SDK references.
# IXO Blocksync GraphQL API
Source: https://docs.ixo.world/api-reference/blocksync-graphql-api
Read-only GraphQL query interface for indexed IXO chain data.
IXO Blocksync is an indexing and query service. It is not the canonical protocol transaction interface.
## Overview
* Use this API for indexed, flexible querying.
* Treat this as a service layer over chain data.
* Use protocol gateways for direct protocol operations.
## Service boundary
* In scope: GraphQL query patterns, filters, and pagination.
* Out of scope: transaction submission and module-level protocol semantics.
## Example queries
```graphql theme={"system"}
query {
entities(first: 10) {
edges {
node {
id
name
type
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
```
```graphql theme={"system"}
query {
entities(
filter: {
type: { equalTo: "ORGANIZATION" }
status: { equalTo: "ACTIVE" }
}
) {
edges {
node {
id
name
status
}
}
}
}
```
## Authentication and endpoints
Verify required credentials and auth patterns by interface.
Confirm endpoint mappings by network and environment.
## Troubleshooting
* **GraphQL `errors` with partial `data`** — Treat the operation as failed if any required selection set is null; fix variables and filters, then retry. Log `extensions` when present for server hints.
* **Auth failures** — Service credentials differ by operator; confirm against [Authentication matrix](/reference/authentication-matrix). Do not reuse protocol wallet keys as GraphQL API keys.
* **Stale or missing entities** — Indexers lag behind chain head; wait for sync or query the same entity via RPC/REST if you need authoritative height.
* **Introspection disabled** — Some deployments turn off schema introspection in production; use a saved schema or dev environment for tooling.
## Related references
Apply consistent pagination patterns across API queries.
Use RPC endpoints for direct blockchain node interactions.
Navigate IXO products, APIs, and SDK references.
# Error Handling
Source: https://docs.ixo.world/api-reference/errors
Comprehensive guide to error handling in IXO API
Effective error handling is essential for ensuring a smooth developer experience and building robust applications. This guide provides an overview of the errors you may encounter when interacting with IXO API.
Errors that occur due to client-side issues.
* **400 Bad Request**: Malformed request or invalid parameters
* **401 Unauthorized**: Authentication required or failed
* **403 Forbidden**: Insufficient permissions
* **404 Not Found**: Resource not found
* **429 Too Many Requests**: Rate limit exceeded
Errors that occur due to server-side issues.
* **500 Internal Server Error**: Unexpected server condition
* **502 Bad Gateway**: Invalid response from upstream
* **503 Service Unavailable**: Server temporarily unable to handle request
## Error Response Structure
IXO API provides informative error responses in JSON format:
```json theme={"system"}
{
"error": {
"code": 400,
"message": "Invalid request parameters",
"details": [
{
"field": "entityId",
"error": "Missing required parameter"
}
]
}
}
```
### Response Fields
* **code**: HTTP status code
* **message**: Human-readable error description
* **details**: Additional error information
## Best Practices
Rely on HTTP status codes to understand error types and handle them appropriately.
For 5xx errors, implement retry logic with exponential backoff.
Validate all input parameters before sending requests to minimize 400 errors.
Monitor and respect rate limits to avoid 429 errors.
## Common Error Solutions
**Solution**: Double-check request syntax and parameters
**Solution**: Verify access token and re-authenticate if needed
**Solution**: Verify user permissions and roles
**Solution**: Retry after delay or contact support
Always log and monitor errors to identify patterns and improve error handling in your applications.
# Blockchain REST API
Source: https://docs.ixo.world/api-reference/grpc-gateway-api
HTTP/JSON gateway reference for IXO Protocol gRPC query services.
The Blockchain REST API is the gateway surface for IXO Protocol query access over HTTP. It is a protocol interface, not an application service API.
## Overview
* Use this API when your client needs HTTP/JSON access to protocol queries.
* Use the RPC API for direct node interaction patterns.
* Use service APIs for IXO Blocksync, IXO Matrix, or Impact Hub Registry workflows.
## Request model
1. Client sends HTTP request.
2. Gateway maps request to gRPC service methods.
3. Gateway returns JSON response.
## Example endpoint shapes
```http theme={"system"}
GET /ixo/entity/{id}
GET /ixo/claims/claims
GET /ixo/token/params
```
## Authentication and endpoints
Authentication requirements vary by deployment.
Confirm required credentials and auth patterns by interface.
Confirm endpoint mappings by network and environment.
## Troubleshooting
* **`404` on REST paths** — Gateway build or route prefix differs by deployment (`/ixo/...` vs legacy prefixes). Compare the served OpenAPI/Swagger document from your node operator.
* **`501 Not Implemented` / empty responses** — The mapped gRPC method may be disabled or not compiled into that binary.
* **CORS errors from browsers** — Prefer server-side or mobile clients for protocol access; if you must call from a browser, use an operator-approved proxy.
* **401/403** — Some deployments gate REST; align headers with [Authentication matrix](/reference/authentication-matrix). For writes, you still sign transactions—REST is often query-only.
## Related references
Use RPC endpoints for direct blockchain node interactions.
Review authentication patterns used across IXO API interfaces.
Navigate IXO products, APIs, and SDK references.
# API reference
Source: https://docs.ixo.world/api-reference/index
Interface reference for IXO Protocol gateways and IXO application services.
This section documents API interfaces only. It does not define protocol concepts, product positioning, or canonical endpoint literals.
For a **single comparison table** (read/write, purpose, links to auth and endpoints), start at [API introduction](/api-reference/intro-apis).
## API surfaces
Direct node-level interface for IXO Protocol transaction and state access.
HTTP/JSON gateway over gRPC query services for IXO Protocol modules.
Indexed query interface for chain data through IXO Blocksync.
Service API for state and ACL operations in IXO Matrix rooms.
Application API for Impact Hub Registry service workflows.
Session endpoint for the IXO USSD gateway — accepts input from telecom gateways and returns USSD responses.
## Boundary between protocol and services
* IXO Protocol APIs: `rpc-api` and `grpc-gateway-api`.
* Service APIs: `blocksync-graphql-api`, `matrix-state-bot-api`, and `registry-api`.
* Protocol concepts and module behavior belong in protocol documentation, not API operation pages.
## Shared references
Confirm canonical endpoint mappings by network and environment.
Verify interface-specific authentication requirements and literals.
Navigate IXO products, APIs, and SDK references.
## Related API guidance
Compare authentication schemes by API surface.
Handle common API and transport failures.
Use cursor and page patterns for large result sets.
# Introduction
Source: https://docs.ixo.world/api-reference/intro-apis
How to choose between IXO Protocol APIs and IXO service APIs.
Use this page to select the right **API surface** before implementation.
## Vocabulary
* **Protocol gateways** — Node-level interfaces to IXO Protocol modules: submit and query chain state via **JSON-RPC** or **REST over gRPC** (Cosmos stack). You typically need a wallet or signer for writes.
* **Service APIs** — Operator-hosted interfaces over **indexed chain data**, **Matrix**, **registry workflows**, or **USSD** sessions. Auth and base URLs are **deployment-specific**; never assume one header works everywhere.
## Comparison matrix
* **Primary purpose:** Transactions, ABCI queries, Tendermint RPC
* **Typical operations:** `broadcast_tx_*`, status, block, tx search
* **Read / write:** Read + write (tx)
* **Auth and endpoints:** [Authentication matrix](/reference/authentication-matrix); [Networks and endpoints](/reference/networks-and-endpoints)
* **Docs:** [Blockchain RPC API](/api-reference/rpc-api)
* **Primary purpose:** HTTP/JSON queries (and tx broadcast where exposed)
* **Typical operations:** Module REST paths, Swagger/OpenAPI per deployment
* **Read / write:** Read; write depends on deployment
* **Auth and endpoints:** Same as RPC—confirm with node operator
* **Docs:** [REST (gRPC gateway)](/api-reference/grpc-gateway-api)
* **Primary purpose:** Indexed queries over chain-derived entities
* **Typical operations:** GraphQL queries (subscriptions if enabled)
* **Read / write:** **Read-only** in docs model
* **Auth and endpoints:** Service operator credentials
* **Docs:** [Blocksync GraphQL API](/api-reference/blocksync-graphql-api)
* **Primary purpose:** Room state, ACLs, automation hooks for Matrix
* **Typical operations:** Bot-specific HTTP endpoints
* **Read / write:** Read + write (room operations)
* **Auth and endpoints:** Service operator credentials
* **Docs:** [Matrix state bot API](/api-reference/matrix-state-bot-api)
* **Primary purpose:** Impact Hub Registry application workflows
* **Typical operations:** CRUD-style registry operations per spec
* **Read / write:** Read + write (per spec)
* **Auth and endpoints:** Often Basic or bearer—confirm matrix
* **Docs:** [Registry API](/api-reference/registry-api)
* **Primary purpose:** Telecom session bridge for USSD menus
* **Typical operations:** Session request/response
* **Read / write:** Write (session replies) + read patterns per spec
* **Auth and endpoints:** Service operator policy
* **Docs:** [USSD gateway API](/api-reference/ussd-api)
For SDK and product naming, see [Product and SDK map](/reference/product-and-sdk-map).
## API families (quick links)
* **IXO Protocol gateways**
* [RPC API](/api-reference/rpc-api)
* [REST (gRPC gateway)](/api-reference/grpc-gateway-api)
* **IXO service APIs**
* [Blocksync GraphQL](/api-reference/blocksync-graphql-api)
* [Matrix state bot](/api-reference/matrix-state-bot-api)
* [Registry](/api-reference/registry-api)
* [USSD gateway](/api-reference/ussd-api)
## Authentication and endpoints
This page does not define canonical auth headers or endpoint literals.
Use canonical auth requirements and literals by interface.
Confirm network-specific endpoint mappings before implementation.
Navigate IXO products, APIs, and SDK references.
## Next steps
Compare protocol and service interfaces from one entry point.
Handle API and transport failures consistently.
Apply cursor and page patterns for large result sets.
# Matrix state bot API
Source: https://docs.ixo.world/api-reference/matrix-state-bot-api
Service API for state and ACL operations in IXO Matrix rooms.
This is a service API for IXO Matrix workflows. It is separate from IXO Protocol gateway APIs.
## Overview
* Use this API to read and manage application state events in Matrix rooms.
* Use this API to manage ACL event content for room-level permissions.
* Do not use this page as a source for protocol transaction behavior.
## Event shapes
```json theme={"system"}
{
"type": "ixo.room.state",
"state_key": "unique_identifier",
"content": {}
}
```
```json theme={"system"}
{
"type": "ixo.room.state.acl",
"state_key": "state_event_key",
"content": {
"read": ["@user:domain.com"],
"write": ["@admin:domain.com"]
}
}
```
## Authentication and endpoints
Confirm required credentials and auth patterns by interface.
Confirm endpoint mappings by network and environment.
## Troubleshooting
* **`403` / ACL denied** — Bot token lacks power level or room membership; verify room ID, bot user ID, and ACL event content.
* **State event rejected** — Invalid `state_key`, oversized `content`, or conflicting types; compare with working examples in [IXO Matrix](/articles/ixo-matrix).
* **Wrong homeserver** — Matrix is federation-aware; confirm `baseUrl` and user IDs match the deployment in [Networks and endpoints](/reference/networks-and-endpoints).
* **Rate limits** — Back off and batch state updates; see [Error handling](/api-reference/errors) for generic HTTP retry guidance.
## Related references
Review authentication patterns used across IXO API interfaces.
Navigate IXO products, APIs, and SDK references.
# Pagination
Source: https://docs.ixo.world/api-reference/pagination
Guide to pagination in the IXO Blocksync GraphQL API
Pagination is crucial for managing large datasets efficiently, ensuring smooth navigation and data retrieval without overwhelming clients or servers.
## Default Pagination
The IXO Blocksync GraphQL API uses a default pagination value of 10 items across all queries.
## Pagination Parameters
Defines the number of records to return in each query.
```graphql theme={"system"}
query {
entities(first: 50) {
edges {
node {
id
name
}
}
}
}
```
Defines the number of records to return, starting from the end of the dataset.
```graphql theme={"system"}
query {
entities(last: 10) {
edges {
node {
id
name
}
}
}
}
```
Cursor to indicate the point in the dataset from which to continue fetching results.
```graphql theme={"system"}
query {
entities(first: 20, after: "YXJyYXljb25uZWN0aW9uOjEw") {
edges {
node {
id
name
}
}
}
}
```
Cursor to navigate backward from a specific point in the dataset.
```graphql theme={"system"}
query {
entities(last: 10, before: "YXJyYXljb25uZWN0aW9uOjIw") {
edges {
node {
id
name
}
}
}
}
```
## Response Structure
A paginated response includes metadata for navigation:
```json theme={"system"}
{
"data": {
"entities": {
"edges": [
{
"node": {
"id": "did:ixo:entity:001",
"name": "Entity One"
}
}
],
"pageInfo": {
"endCursor": "YXJyYXljb25uZWN0aW9uOjIw",
"hasNextPage": true
}
}
}
}
```
### Response Fields
* **edges**: Array of results
* **pageInfo.endCursor**: Reference point for next results
* **pageInfo.hasNextPage**: Indicates more data availability
## Best Practices
Use 20-100 items per query for optimal performance
Check `hasNextPage` to determine if more data is available
Use cursor values from responses, don't hardcode them
Implement rate limiting strategies to avoid 429 errors
## Error Handling
Occurs with invalid cursor values. Always use cursors from previous responses.
Implement retry logic with exponential backoff when rate limits are reached.
For optimal performance, implement client-side caching of paginated results when appropriate.
# Registry API
Source: https://docs.ixo.world/api-reference/registry-api
Application service API reference for Impact Hub Registry workflows.
This page covers the Impact Hub Registry service API. It is not a direct IXO Protocol gateway and should be treated as an application/service surface.
## Overview
* Service scope includes registry-facing workflows such as project, household, device, credit, and claim reporting interfaces.
* Protocol-level claim semantics and module transactions belong to IXO Protocol API pages.
## Authentication
Registry deployments can use service-specific credentials. The historical examples for this surface include HTTP Basic auth.
```http theme={"system"}
Authorization: Basic
```
Do not assume one auth scheme across all registry environments. Confirm active requirements in `/reference/authentication-matrix`.
## Endpoint groups
* System health and API docs
* Household and device reporting
* Fuel and claims reporting
* Credit lifecycle reporting
## Known literal handling
Historical environment literals for this surface have appeared in previous docs. This page no longer treats those values as canonical source of truth.
Use network and environment endpoint mappings as source of truth.
Confirm active authentication requirements before integration.
## Troubleshooting
* **`401 Unauthorized` with Basic auth** — Wrong username/password or environment rotated credentials; re-read the deployment row in [Authentication matrix](/reference/authentication-matrix).
* **`403 Forbidden`** — Authenticated but missing role or scope for that registry route; check operator RBAC and which program the credentials belong to.
* **`404` on resource paths** — Registry API versions and path prefixes differ by deployment; confirm OpenAPI/base URL with your operator ([Networks and endpoints](/reference/networks-and-endpoints)).
* **Payload validation errors** — Compare field names to the operator’s schema; many issues are missing required reporting fields, not transport failures ([Error handling](/api-reference/errors)).
## Related references
Follow task-oriented guidance for registry workflows.
Review authentication patterns used across IXO API interfaces.
Navigate IXO products, APIs, and SDK references.
# Blockchain RPC API
Source: https://docs.ixo.world/api-reference/rpc-api
Node-level API interface for IXO Protocol transactions and state queries.
This page documents the RPC interface family for IXO Protocol. It does not document application service APIs such as Impact Hub Registry, IXO Blocksync, or IXO Matrix.
## Overview
* Use this interface for protocol-level operations against chain nodes.
* Prefer this when you need direct interaction with IXO Protocol modules.
* For indexed or application-service workflows, use service APIs in this section instead.
## Protocol boundary
* In scope: chain state queries and transaction submission patterns.
* Out of scope: service-specific business endpoints and off-chain workflow APIs.
## Authentication and endpoints
Authentication depends on node and deployment policy.
* Check `/reference/authentication-matrix` for active auth requirements.
* Check `/reference/networks-and-endpoints` for network-specific RPC endpoints.
## Example message shapes
```protobuf theme={"system"}
message MsgCreateEntity {
string creator = 1;
string entity_type = 2;
string entity_status = 3;
}
```
```protobuf theme={"system"}
message MsgSubmitClaim {
string creator = 1;
string collection_id = 2;
string claim_id = 3;
}
```
## Troubleshooting
* **`connection refused` / TLS errors** — Wrong host, port, or TLS termination. Confirm the literal in [Networks and endpoints](/reference/networks-and-endpoints) and your operator’s current RPC URL.
* **`invalid JSON-RPC` / parse errors** — Request body not valid JSON-RPC 2.0; include `jsonrpc`, `id`, `method`, and `params` as required by the method.
* **Transaction broadcast failures** — Inspect `code`, `codespace`, and `rawLog`. Common causes: insufficient fees, wrong `chain-id`, sequence mismatch, or missing signer permissions. See [Error handling](/api-reference/errors) and [Claims management](/guides/dev/ixo-claims#troubleshooting).
* **Auth on RPC** — Many nodes allow unauthenticated read; writes require a valid signed tx, not an API key. Confirm policy in [Authentication matrix](/reference/authentication-matrix).
## Related references
Access protocol queries over HTTP/JSON through the gRPC gateway.
Query indexed chain data through the IXO Blocksync service layer.
Navigate IXO products, APIs, and SDK references.
# USSD gateway API
Source: https://docs.ixo.world/api-reference/ussd-api
Endpoint reference for the IXO USSD gateway session API.
## Overview
The IXO USSD gateway exposes a single session endpoint that telecom gateways call for each user interaction, plus debug and health endpoints for operators.
All endpoints accept and return JSON unless otherwise noted. The main session endpoint returns plain text in the USSD response format.
## Authentication
The `/api/ussd` endpoint does not require authentication by default. It is intended to be called by your telecom gateway server, not directly from a browser. Restrict access at the network or reverse-proxy layer in production.
## Base URL
```text theme={"system"}
http://YOUR_SERVER:3000
```
The default port is `3000`. Set `PORT` in your environment to override.
## Session endpoint
### POST /api/ussd
Processes a USSD interaction. Called by the telecom gateway once per user input during a session.
**Request**
```json theme={"system"}
{
"sessionId": "string",
"serviceCode": "string",
"phoneNumber": "string",
"text": "string"
}
```
* **Type:** `string`
* **Required:** yes
* **Description:** Unique session identifier assigned by the telecom gateway.
* **Type:** `string`
* **Required:** yes
* **Description:** USSD service code the user dialled, for example `*1234#`.
* **Type:** `string`
* **Required:** yes
* **Description:** User phone number in E.164 international format, for example `+260971234567`.
* **Type:** `string`
* **Required:** yes
* **Description:** User input accumulated during the session; empty string on initial dial.
**Validation rules**
* `phoneNumber` must be E.164 format
* `serviceCode` must match USSD format, e.g. `*1234#` or `*123*456#`
* `text` maximum 182 characters (USSD protocol limit)
* `sessionId` maximum 100 characters
**Response**
Plain text. The first word indicates whether the session continues or ends.
```text theme={"system"}
CON