Calling the Tino API

Customer apps and software call the Tino API on the customer's behalf through the gateway https://api.tino.vn/v1/<route>: each route runs the UserAPI route of the same name with the customer's account, within the scopes of the token. Request bodies and responses keep the UserAPI format (see Personal data). AI assistants call the same routes as tools through the MCP server.

Updated: 2026-10-21. Routes, scopes, names and parameters match the live gateway; sample responses are real answers with personal data masked.

Authentication

Every route needs the header Authorization: Bearer <token>, with one of two token types:

Token	Prefix	Where it comes from	Can call
App token (access token)	`tinoat_`	Sign in with Tino: the customer agrees to grant scopes to the app	routes in the scopes the customer approved; never `domains:owner`
Personal API token	`tinopat_`	created by the customer at `https://auth.tino.vn/en/me/security`, in the API tokens section	routes in the scopes the customer chose, including `domains:owner` (IP restriction required); only from IPs in the list, if one is set

curl https://api.tino.vn/v1/details -H "Authorization: Bearer $TINO_TOKEN"

Each route page lists the required scope and the token types that can call the route.

Exception: public routes need no token and are called on https://api.tino.vn directly (no /v1); currently Domain whois lookup (GET /whois/<domain>).

Sending parameters

Path parameters: the docs write @id, @vmid…; replace them with real values, for example GET /v1/service/12345.
GET, DELETE: parameters go in the query string.
POST, PUT: JSON body with Content-Type: application/json. The gateway also reads the query string and form bodies (application/x-www-form-urlencoded).
Pagination (on list routes that support it): page starts at 0, perpage is the number of rows per page; the response has page.current, page.total.
Filtering and sorting: filter[<key>]=<value>, orderby=<field>|DESC or |ASC.

Personal data

The /v1 gateway returns the route's response unchanged, including identity data of the account, contacts and domain registrants (ID document numbers, date of birth, phone number, address, tax code): a token that can call it belongs to the account owner or was authorized by the account owner. Keep tokens like passwords; do not log these fields, and do not store them when the app does not need them.

The MCP server, by contrast, filters out identity fields before sending results to the AI assistant.

Errors

The gateway rejects requests with the body {"error": ["<code>"]}; 401 errors and insufficient_scope also carry the header WWW-Authenticate: Bearer error="<code>" (with scope and resource_metadata for MCP clients).

HTTP	`error`	Cause	Fix
401	`invalid_token`	the token is wrong, expired or revoked	apps refresh the token; for personal tokens, create a new token
403	`insufficient_scope`	the token lacks the route's scope, or the route is not in the gateway	request more scopes (apps) or create a token with more scopes (personal tokens)
403	`ip_not_allowed`	a personal API token was used from an IP outside its allowed list	call from a listed IP, or create a token with a new IP list
403	`ipnotallowed`	the calling IP is blocked by Tino	contact Tino

Business errors of each route (for example, a service that does not exist) keep the UserAPI response, usually HTTP 200 with {"error": ["<code>"]}; successful actions usually return {"info": ["<code>"]}.

Route list

Each route has its own page: parameters, cURL, JavaScript and PHP examples, sample response; the index by product is at API Reference, the machine-readable version at /openapi.json. Markdown for LLMs: add .md to the page path (for example /en/docs/api/get-details.md); everything is in /llms-full.txt.