TakVPN Open API

Sell VPN under your own brand

Automate plan purchases, config delivery and renewals with a simple REST API. Pay from your wallet, name configs with your brand and integrate in minutes.

Get your API key Read the docs

REST · JSON
Bearer tvp_…
API v1.1.0

~/integration

White-label configs

Set a brand prefix once and every new config carries your name instead of ours.

Full automation

Buy plans, download configs, renew, regenerate and archive peers — all over HTTP.

Wallet billing

No invoices to reconcile. Purchases are paid from your Toman or USDT wallet.

Locked-down tokens

Bearer tokens with optional expiry and IP allowlists. Revoke any time.

Quickstart

From zero to your first VPN config in three requests.

1
Create an API token
Open Dashboard → Developers and create a token. Copy it once and store it as an environment variable on your server.
Get your API key
Terminal
```
export TAKVPN_TOKEN="tvp_your_token_here"
```
2
Check your account
Call /me to confirm the token works and see your wallet balances.
```
curl -sS -X GET "https://api.takvpn.com/api/open/v1/me" \
  -H "Authorization: Bearer $TAKVPN_TOKEN"
```

Buy a plan

POST /orders charges your wallet and starts provisioning a VPN peer. Poll /vpn to get its config.

curl -sS -X POST "https://api.takvpn.com/api/open/v1/orders" \
  -H "Authorization: Bearer $TAKVPN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":1,"currency":"IRT"}'

Authentication

Every request needs your token in the Authorization header. Tokens act as your customer account, so anything you can do on the dashboard VPN and order pages, the token can do too.

Request headers

Authorization: Bearer tvp_…
Accept: application/json

Base URL

https://api.takvpn.com/api/open/v1

IP allowlist

Optionally restrict a token to specific IPs or CIDR ranges. Requests from other addresses are rejected.

Keep tokens server-side

Never put tokens in mobile apps, browsers or public repos. Use short expiries and revoke a token immediately if it leaks.

Security

How the API protects your account, and what you should do on your side.

Bearer header only

Tokens are accepted only in the Authorization header. Requests with ?token= in the URL or session cookies are rejected, so tokens never end up in logs or browser history.

Hashed, shown once

We store only a SHA-256 hash of each token and compare it in constant time. The plaintext is shown once when you create it.

IP allowlists that cannot be spoofed

Lock a token to your server IPs or CIDR ranges. The client IP comes from our edge proxy; forwarding headers sent by clients are ignored. Other IPs get 403 ip not allowed.

Expiry and instant revoke

Give tokens an expiry date and revoke them at any time in the dashboard. Revoked, expired or suspended-account tokens get 401 immediately.

Private, non-cacheable responses

Every response is sent with Cache-Control: no-store and an X-Request-ID. Quote the request ID when you contact support.

Server-to-server only

The Open API has no CORS. Call it from your backend and keep the token in a secret store or environment variable — never in a website, mobile app or public repository.

Token leaked?

Revoke it in Dashboard → Developers right away and create a new one. Revocation takes effect on the next request.

Brand prefix

Configs are named with a prefix. Set your own brand in the dashboard and every new peer is named after you — existing peers keep their names.

Default

takvpn-starter-30d12345

With your brand

mybrand-starter-30d12345

2–24 characters: lowercase letters, digits and hyphens, starting with a letter.

Set your brand

Wallet & billing

Creating and renewing peers is paid from your account wallet (Toman or USDT, chosen per request). Top up in the dashboard before running large batches.

HTTP 402 — insufficient balance

When the wallet cannot cover a purchase or renewal the API returns 402 and nothing is charged. Top up and retry.

Reseller pricing

Reseller accounts get their own prices from GET /reseller/plans. Other accounts receive 403 on that endpoint.

Top up wallet

API reference

22 endpoints, generated live from our OpenAPI specification.

OpenAPI YAML

Account1

Plans3

Orders3

VPN peers15

Errors

The API uses standard HTTP status codes. Error responses have a JSON body with an error message.

400
400 — Bad request
The JSON body is malformed or a field is invalid (for example currency must be USDT or IRT).
401
401 — Unauthorized
The token is missing, wrong, expired or revoked. Create a new token in the dashboard.
402
402 — Insufficient balance
Your wallet cannot cover the purchase or renewal. Top up and retry.
403
403 — Forbidden
The token is IP-restricted and the request came from another address (ip not allowed), or the endpoint is not available to your role.
404
404 — Not found
The plan slug or peer ID does not exist or does not belong to you.
409
409 — Conflict
The peer is not in a state that allows this action (not eligible, already in progress, blocked by admin).
429
429 — Rate limited
Too many requests. Wait a moment and retry with backoff.
5XX
502 / 503 — Upstream or sales unavailable
The VPN server failed (you were not charged) or plan sales are temporarily disabled. Retry later.

Error response

HTTP/1.1 402 Payment Required
X-Request-ID: api-7f3c9b/ZkGq8VtqKx-000043

{
  "error": "insufficient balance"
}

Match on the error code in the body (for example insufficient balance or ip not allowed) — several conditions can share an HTTP status. Each endpoint in the reference lists its possible errors with examples.

Limits

Limits are applied per IP, per token and per account. All tokens of one account share the account limits. These are the default values.

Limit	Allowed	Applies to
Per IP address	60 / minute	All Open API requests (checked before authentication)
Per token	60 / minute	All authenticated requests
Purchases per account	10 / minute	POST /orders, POST /orders/bulk
Peer changes per account	10 / minute	enable, disable, bulk, delete, retry, renew, regenerate
Config downloads per account	20 / hour	GET /vpn/{id}/download
Key regeneration per peer	once every 7 days	POST /vpn/{id}/regenerate

Rate limit headers (429 response)

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767225660
X-Request-ID: api-7f3c9b/ZkGq8VtqKx-000042

{ "error": "rate limited" }

Handle 429 gracefully

Read X-RateLimit-Remaining on every response and slow down before you hit zero. On 429 wait Retry-After seconds, then retry with exponential backoff and jitter. Do not retry purchases blindly — check GET /orders first.

Other limits

Up to 5 active tokens per account
Up to 20 configs per bulk order
Up to 100 peer IDs per bulk enable/disable
Notes up to 512 characters

Frequently asked questions

Who can use the API?

Every TakVPN account. Create a token in Dashboard → Developers — no approval needed.

What happens when my wallet runs out?

Purchases and renewals return HTTP 402 (insufficient balance) and nothing is charged. Top up your wallet and retry the request.

Can I change my brand prefix later?

Yes. The new prefix applies to configs created after the change; existing peers keep their names.

I lost my token. Can I see it again?

No — tokens are shown only once. Revoke the old one and create a new token.

How do I get the config for a new peer?

After POST /orders, list your peers with GET /vpn and download the config with GET /vpn/{id}/download once it is active.

Start building in minutes

Create a token, set your brand and make your first request today.

Get your API key