Skip to main content

Integration Overview

The Integration service is the primary public-facing HTTP service for the tokenization platform. All client integrations talk to it through the API Gateway; the gateway handles authentication routing, while this service owns business logic.

Base URLs​

EnvironmentBase URL
Testhttps://test-integration-api.tokenizationtr.com
Productionhttps://integration-api.tokenizationtr.com

API Versions​

The integration service exposes two versioned API groups:

VersionPrefixPurpose
v2/v2External API consumed by integrations and partner platforms. Covered by the sections below.
v1/v1Internal node-to-node discover API (legacy / back-channel). Not intended for external consumers.

Endpoint Groups​

Authentication (/v2/oauth)​

OAuth-style credentials-to-token exchange. See Create a Token.

Admin (/v2/admin/**)​

Supervisor-facing endpoints for managing nodes, tokens, fees, KYC, OTC rules, supervisors, oracles, currency tokens, and categories. See the Admin Token list endpoint to get started.

Users (/v2/users/**)​

End-user endpoints for purchases, rentals, OTC, secondary-market orders, token balances, and user profiles/wallets. See Get Tokens by User and the surrounding routes.

Blockchain (/v2/blockchain)​

Utility endpoints for on-chain data such as Gas Fee. Public — no authentication required.

Webhooks (/v2/webhooks)​

Inbound webhook receiver used by external chain services to push transaction updates. Protected by HTTP Basic auth (not JWT). See Receive Webhook.

Authentication​

All /v2/admin/** and /v2/users/** endpoints require a JWT access token:

Authorization: Bearer <access_token>

Obtain a token via POST /v2/oauth/token using the password grant type. Refresh with the refresh_token grant.

Protected endpoints also enforce client-level guards applied as middleware:

  • Client JWT authentication — the access token is bound to a registered API client.
  • mTLS — when the client has require_certificate = true, the integration backend verifies the SHA-256 fingerprint forwarded by NGINX (ssl-client-fingerprint) against the stored cert_fingerprint. Mismatches return 403. See Create Client.
  • IP allow-list — the requesting IP must match an entry (single IP or CIDR) in the client's allowed_ips.
  • Rate limit — per-client per-second / per-minute / per-hour ceilings. 429 surfaces with Retry-After and X-Ratelimit-* headers.
  • Usage limit — per-client monthly score quota (see Usages / Score). 429 surfaces with X-MonthlyLimit-* headers.

Request Lifecycle​

┌────────┐    ┌─────────┐    ┌──────────────┐    ┌───────────┐
│ Client │───▶│ Gateway │───▶│ Integration  │───▶│ Admin svc │
│        │    │ (proxy) │    │  (this svc)  │    │  (async)  │
└────────┘    └─────────┘    └──────────────┘    └───────────┘
  1. Client sends request with Authorization: Bearer … (and, when required, an mTLS client certificate) to the gateway.
  2. Gateway validates JWT, records audit log, and reverse-proxies to Integration.
  3. Integration re-validates the token, runs mTLS / client / IP / rate / usage middleware, then dispatches business logic.
  4. Long-running operations (contract deploys, token updates against listed tokens, withdrawals, etc.) are queued to the Admin service via RabbitMQ; clients poll via the relevant /transactions/{id} endpoint for completion.

Blockchain-Pending Read Guarantee​

Admin write endpoints that may end up enqueuing a blockchain transaction (e.g. Update Token, Update Token Metric) commit the speculative new state to the tokens collection immediately but do not write a token_histories snapshot until the blockchain-confirm consumer settles the transaction. User-facing reads (Get Token By User, Get Tokens By User) overlay value/metric from the latest token_histories row — so end users keep seeing the previous confirmed snapshot until the chain settles. Off-chain edits (name, description, oracle, rental terms, etc.) write the history row synchronously and are visible on the very next read.

Error Format​

Errors are JSON objects with a machine-readable code and a human message. Example:

{
  "code": -1,
  "domain": 0,
  "message": "current user id not found"
}

Postman Collection​

A ready-to-import Postman collection covering all public endpoints is available from the Introduction page.