# Personal API tokens

Personal API tokens let the customer's own software (a WHMCS module, a domain management script, your own tool…) call the Tino API without signing in. Customers create tokens themselves in Tino ID and choose the scopes, expiry and allowed IPs; the software sends the token in the header `Authorization: Bearer tinopat_…` to the gateway `https://api.tino.vn/v1/<route>`.

Updated: 2026-10-27.

## When to use

| You need | Use |
| --- | --- |
| Your own software calls the API with your Tino account | Personal API token (`tinopat_`) |
| Your app serves many Tino customers, each of whom signs in and approves | [Sign in with Tino](/en/docs/oauth) (`tinoat_`) |
| Claude, ChatGPT work with your Tino account | [MCP connection](/en/docs/mcp): OAuth sign-in, no token needed |
| Other MCP apps (Cursor, VS Code, n8n…) | [MCP connection](/en/docs/mcp#other-mcp-apps-cursor-vs-code-n8n): OAuth sign-in (the app registers itself); a personal API token when the app does not support MCP OAuth or runs on a server that cannot open a browser |

Only personal API tokens can carry the `domains:owner` scope (get the EPP code, change the domain registrant); OAuth apps are never granted this scope.

## Creating a token

1. Sign in to Tino ID, open `https://auth.tino.vn/en/me/security`, go to the **API tokens** section, and click **Create token**.
2. Name the token (1–64 characters), for example "WHMCS module".
3. Choose scopes: at least one scope from the table below. When you choose the write scope of a group, the interface also selects the read scope of the same group.
4. Choose the expiry: 30 days, 90 days, 1 year (default) or no expiry.
5. IP restriction (optional, unless you choose `domains:owner`): IPv4 or IPv6 addresses or CIDR ranges, separated by spaces or commas, up to 20. Empty: the token can be used from any IP.
6. Copy the token right away: it is shown only once, when it is created. Tino stores only a SHA-256 hash; the token list keeps only the last 4 characters so you can recognize it.

Each sign-in account can have up to 20 tokens. A token has the form `tinopat_` + 43 characters (base64url).

| Scope | Allows |
| --- | --- |
| `profile:read` | View account details |
| `profile:write` | Edit account details |
| `services:read` | View services, including service login details |
| `services:write` | Service management |
| `domains:read` | View domains |
| `domains:write` | Register, renew and manage domains |
| `domains:owner` | Get domain transfer codes (EPP) and change domain registrants; IP restriction required |
| `domains:registrant` | View and complete the registrant dossier of domains awaiting registration (includes ID number, date of birth); IP restriction required |
| `dns:read` | View DNS records |
| `dns:write` | Edit DNS records |
| `billing:read` | View invoices and payments |
| `billing:write` | Make payments and top up |
| `orders:write` | Order services: cart, quotes, create orders (paying from balance also needs the Payments permission) |
| `tickets:read` | View support tickets |
| `tickets:write` | Create and reply to tickets |
| `tinopay:read` | View TinoPay: receiving accounts, transactions, webhooks |
| `tinopay:write` | Manage TinoPay: virtual accounts, webhooks, notifications, Sapo integration |
| `tinopay:owner` | Create TinoPay API tokens and link receiving bank accounts; IP restriction required |
| `builder:read` | View TinoPage Builder websites |
| `builder:write` | Manage TinoPage Builder websites: create, publish, custom domains |
| `waf:read` | View websites protected by TinoWAF and the event log |
| `waf:write` | Manage TinoWAF: websites, protection level, origin servers, IP rules |

Each scope opens a group of routes; see the routes of each scope at [Calling the Tino API](/en/docs/api).

## `domains:owner` and IP restriction

`domains:owner` opens [get the EPP code](/en/docs/api/get-domain-id-epp) (`GET /v1/domain/@id/epp`), [change domain contacts and registrant](/en/docs/api/put-domain-id-contact) (`PUT /v1/domain/@id/contact`) The four [registrant dossier routes of waiting domains](/en/docs/domain-registrant) have their own scope, `domains:registrant`, also personal tokens with an IP restriction only. Anyone with the two `domains:owner` routes can transfer the domain elsewhere, so a token with `domains:owner` must have an IP list: Tino refuses to create the token when the list is empty. A leaked token still cannot transfer domains from another machine.

When called from an IP outside the list, every route of the token returns 403 `ip_not_allowed`.

## Calling the API

```bash
curl https://api.tino.vn/v1/domain -H "Authorization: Bearer tinopat_…"
```

The token calls the API as the account that created it, only within the chosen scopes. See the body, parameters and response of each route in the [API Reference](/en/docs/reference).

Keep the token like a password: store it in an environment variable or the server's secret store, never in source code, URLs or the browser.

## Monitoring and revoking

The token list at `https://auth.tino.vn/en/me/security` shows the name, scopes, allowed IPs, creation time, last use (updated at most once per minute) and expiry. Expired tokens show the **Expired** label.

Click **Revoke** to delete a token: software using it gets 401 `invalid_token` on its next call. To change the scopes, expiry or IPs, create a new token, then revoke the old one.

## Errors

| HTTP | `error` | Cause | Fix |
| --- | --- | --- | --- |
| 401 | `invalid_token` | the token is wrong, expired or revoked | create a new token |
| 403 | `ip_not_allowed` | called from an IP outside the token's allowed list | call from a listed IP, or create a token with a new IP list |
| 403 | `insufficient_scope` | the token lacks the route's scope | create a token with more scopes |
| 403 | `ipnotallowed` | the calling IP is blocked by Tino | contact Tino |

When you create a token, Tino shows an error if the name is empty or longer than 64 characters, no scope is chosen, the expiry is invalid, an IP or IP range is invalid (or there are more than 20), `domains:owner` is chosen without IPs, or the account already has 20 tokens.