> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway & Authentication

> XHuoAPI API gateway endpoints, headers, authentication, and common errors.

All XHuoAPI APIs are served from `https://api.xhuoapi.ai/v1` and authenticated via **Bearer Token**.

## Endpoints

<CardGroup cols={2}>
  <Card title="API Gateway" icon="globe">
    `https://api.xhuoapi.ai/v1`

    Entry point for all business calls.
  </Card>

  <Card title="Developer Console" icon="browser">
    `https://api.xhuoapi.ai`

    Subscriptions, credentials, usage.
  </Card>

  <Card title="Identity" icon="key">
    `https://api.xhuoapi.ai`

    SSO and OAuth2 endpoints.
  </Card>

  <Card title="Status" icon="signal">
    `https://xhuoapi.ai`

    Availability and incident history.
  </Card>
</CardGroup>

## Obtain an API Token

<Steps>
  <Step title="Register">
    Sign up at [platform.xhuoapi.ai](https://api.xhuoapi.ai).
  </Step>

  <Step title="Subscribe">
    Open the detail page of the service you want (Midjourney / Suno / Claude / …) and purchase a package or claim a trial.
  </Step>

  <Step title="Create a credential">
    On the service's "Credentials" tab, click "Create" and copy the returned Token — that's your API Key.
  </Step>
</Steps>

## Kinds of tokens

* **Business token**: created on each service page at [platform.xhuoapi.ai](https://api.xhuoapi.ai); used to call business endpoints on `api.xhuoapi.ai`. Depending on the application it is bound to, billing comes from either a per-service application (instance balance) or a general-scope application (general balance).
* **Platform token** (prefix `platform-`): for platform management APIs (accounts, subscriptions). **Do NOT** use for business calls.

## Request headers

```
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
```

| Field           | Required | Notes                                          |
| --------------- | -------- | ---------------------------------------------- |
| `Authorization` | Yes      | `Bearer ` prefix (mind the space) + your Token |
| `Content-Type`  | POST     | `application/json`, UTF-8                      |

## Common auth / billing errors

The `error.code` values below come from `PlatformGateway`'s real exception definitions. The body shape is `{"error": {"code": "...", "message": "..."}, "trace_id": "..."}` — **no `success` field** in synchronous errors.

### 401 — Invalid token

```json theme={null}
{
  "error": {
    "code": "invalid_token",
    "message": "The specified token is invalid or wrong."
  },
  "trace_id": "2efa9340-b21b-4e26-9e14-4aac95f343ab"
}
```

Possible `error.code`:

* `invalid_token` — token is wrong or revoked
* `token_expired` — token has expired
* `token_mismatched` — token does not belong to the requested service (e.g. service credential used on a different service)

### 400 — Bad request

* `bad_request` — JSON payload is malformed
* `no_token` — missing `Authorization` header

### 403 — Out of balance / blocked

```json theme={null}
{
  "error": {
    "code": "used_up",
    "message": "Your balance is not sufficient for current request, please buy more in XHuoAPI https://api.xhuoapi.ai"
  },
  "trace_id": "..."
}
```

* `used_up` — instance balance and / or general balance is exhausted
* `disabled` — credential or application is disabled
* `forbidden` — upstream content moderation rejected the request

### 404 — Unknown endpoint

* `no_api` — path is not registered

### 429 — Rate limited

```json theme={null}
{
  "error": {
    "code": "too_many_requests",
    "message": "You have exceeded the rate limit."
  },
  "trace_id": "..."
}
```

Use exponential backoff before retrying.

### 500 / 504

* `api_error` — gateway or upstream internal error
* `timeout` — upstream inference timed out

## Security best practices

* **Never** hard-code the Token in browser / mobile / desktop code — always proxy through your own backend
* Store the Token in env vars or a secrets manager
* Issue distinct Tokens for dev / staging / prod
* Revoke and re-issue immediately if you suspect leakage

## Next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/en/quickstart">
    Run your first request
  </Card>

  <Card title="Response format" icon="brackets-curly" href="/en/concepts/responses">
    Success & error fields
  </Card>

  <Card title="Async tasks" icon="arrows-rotate" href="/en/concepts/async-tasks">
    Polling & webhook callbacks
  </Card>

  <Card title="API reference" icon="code" href="/en/api-reference">
    Interactive API docs
  </Card>
</CardGroup>