Mobile Api

Overview

Base conventions for integrating with the HTP mobile API.

Base URL

All application routes are mounted under:

/api/v1

Token issuance for third-party clients now uses the same mobile API host:

Mobile API base: <MOBILE_API_BASE_URL>/api/v1
Connect token route: POST /api/v1/connect/token

There is no separate token-service base URL required for this flow.

A key bootstrap endpoint in this integration is:

POST /api/v1/sys/key-pair to start the optional request-encryption handshake.

Headers You Should Send

Header	Required	Notes
`Content-Type: application/json`	Yes for JSON bodies	All examples below use JSON.
`Accept-Language`	Optional	Current handlers document `en` and `zh`. If omitted, the API falls back to English.
`Authorization: Bearer <access_token>`	Required on protected routes	Public auth endpoints are whitelisted, but most business endpoints require this.
`X-Agent-ID`	Required for `/connect/token`	Agent UUID provided by HTP.
`X-Signature`	Required for `/connect/token`	HMAC-SHA256 signature in lowercase hex.
`Device-ID`	Optional	Used for device-scoped session behavior.
`Device-Name`	Optional	Reserved for client device metadata.

Response Format

Successful responses use a shared envelope:

{
  "trace_id": "",
  "status_code": 200,
  "message": "Success",
  "data": {}
}

Typical success codes:

200 for reads and most mutations.
201 for POST /api/v1/auth/register.

trace_id exists in the payload schema, but it may be empty on successful responses. It is more consistently useful on error payloads.

Important Error Handling Note

Most HTTP error responses are currently returned with an HTTP transport status of 200, while the real failure code is inside the JSON body as status_code.

Handle failures using the response payload, for example:

{
  "status_code": 401,
  "message": "Authentication required",
  "trace_id": "2a6d1a45d8c9402d",
  "data": null
}

Optional Encrypted Payload Wrapper

Auth routes and some write endpoints pass through DecryptField() middleware. That means you can send either:

Plain JSON with the business fields directly.
An encrypted wrapper that the server decrypts before validation.

Encrypted wrapper shape:

{
  "key_version": "c2f1d9a4",
  "salt": "base64-salt",
  "data": "base64-ciphertext"
}

Any extra top-level fields outside that wrapper are merged back into the decrypted payload.

Bootstrap the encryption session

Use POST /api/v1/sys/key-pair before sending encrypted data.

Request:

{
  "key": "client-public-key"
}

Response:

{
  "trace_id": "2a6d1a45d8c9402d",
  "status_code": 200,
  "message": "Success",
  "data": {
    "server_pub_key": [12, 44, 91, 7],
    "key_version": "c2f1d9a4"
  }
}

Public vs Protected Routes

For client token issuance, use:

POST /api/v1/connect/token

On mobile API, these routes are public in the current middleware setup:

POST /api/v1/connect/token
POST /api/v1/auth/forgot-password
POST /api/v1/auth/reset-password
POST /api/v1/auth/logout
GET /api/v1/countries
POST /api/v1/sys/key-pair
GET /api/v1/sys/networks
GET /api/v1/info

Everything else should be treated as protected unless documented otherwise.