# Customer API > Manage TrueProxies services, invoices and connection strings over HTTPS. Learn API key scopes, authentication, rate limits, idempotency and error handling. Source: https://docs.trueproxies.com/proxy-instructions/api/ The customer API lets scripts and integrations do what the dashboard does: list your services, generate connection strings, read usage, manage trusted IPs, browse prices, and create and pay invoices. - Base URL: `https://api.trueproxies.com` - Every path starts with `/v1/` - OpenAPI 3.1 document: [`https://api.trueproxies.com/v1/openapi.json`](https://api.trueproxies.com/v1/openapi.json) - Every operation, with parameters and response fields: [API reference](https://docs.trueproxies.com/api/) ## Create an API key In the dashboard, open **API** and create a key. Give it a name, choose only the scopes the script needs, and pick an expiry of 30, 90 or 365 days. You can have up to 10 active keys and revoke any of them immediately. Send the key as a bearer token: ```bash curl https://api.trueproxies.com/v1/me \ -H "Authorization: Bearer tp_api_YOUR_KEY" ``` > **Caution** > > An API key manages your account. It is not your proxy password, and it never works as a proxy credential. Keep it out of client-side code and public repositories. `GET /v1/catalog` is the only operation that needs no key. It lists offers, cities and payment providers. ## Scopes | Scope | Allows | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | `services:read` | Account, services, usage, analytics and live metrics | | `proxy:read` | Generate connection strings, read the proxy username and password, run an end-to-end check, list trusted IPs | | `proxy:write` | Change the proxy password, add and remove trusted IPs | | `billing:read` | Your current prices, invoices and invoice PDFs | | `billing:write` | Create, pay and cancel invoices | | `reseller:read` | Managed customers, wallet balance and wallet transactions | | `reseller:write` | Create, edit, suspend, resume and close managed customers, and change their proxy settings on their behalf | | `reseller:purchase` | Buy for a managed customer, pay with the wallet and fund the wallet. The only permission that can spend the wallet | A request with a missing scope returns `403`. ## Common tasks List your services: ```bash curl https://api.trueproxies.com/v1/services \ -H "Authorization: Bearer tp_api_YOUR_KEY" ``` Generate connection strings for a service (`proxy:read`). Use only the targeting and session options listed in that service’s capabilities: ```bash curl -X POST https://api.trueproxies.com/v1/services/SERVICE_ID/endpoints \ -H "Authorization: Bearer tp_api_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"country": "us", "count": 5, "format": "user:pass@host:port"}' ``` The response is `{"lines": [...]}`. Each line contains your proxy credentials, so treat the output as a secret. Buy a plan (`billing:write`). Creating an invoice charges nothing; paying it returns a checkout link: ```bash curl -X POST https://api.trueproxies.com/v1/invoices \ -H "Authorization: Bearer tp_api_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c0f7e-2b0e-4d4e-9d1a-4c1f3a9b2e10" \ -d '{"offer_key": "OFFER_KEY"}' curl -X POST https://api.trueproxies.com/v1/invoices/INVOICE_ID/pay \ -H "Authorization: Bearer tp_api_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 0d9e5b1a-7c3f-4a8e-b2d6-9f4e1c7a3b58" \ -d '{"provider": "stripe"}' ``` Take `offer_key` from `GET /v1/catalog` or `GET /v1/catalog/priced`. The pay call returns `checkout_url` and `expires_at`; open the link to complete the payment. `provider` is `stripe` (card) or `cryptomus` (crypto). An unpaid invoice can be cancelled with `POST /v1/invoices/{id}/cancel`. ## Retries and idempotency Send an `Idempotency-Key` header on invoice creation, payment and wallet top-ups; API-key requests without one are refused with `400`. Repeating the same request with the same key replays the first response, with `Idempotency-Replayed: true`, instead of buying or paying twice. Reusing a key for a different request returns `409`, as does a repeat that arrives while the first is still running. Never retry a payment automatically after an uncertain result. Read the invoice status first with `GET /v1/invoices/{id}`: `open`, `paid` or `cancelled`. ## Rate limits Each account gets 300 requests per minute, shared across all of its keys. Over the limit, the API returns `429` with a `Retry-After` header; wait that many seconds before the next request. ## Responses and errors - Timestamps are ISO 8601. - Money is in cents, in USD. - Responses with account data carry `Cache-Control: no-store` and an `X-Request-ID` header. Include the request ID when you contact support. Errors return JSON with a machine-readable `code`, a `message`, and optional `details` for the values your code needs to act on: ```json { "code": "INVOICE_NOT_PAYABLE", "message": "invoice is past due" } ``` | Code | Meaning | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `BAD_REQUEST` | A parameter or body field is invalid | | `UNAUTHENTICATED` | Missing, expired or revoked API key | | `FORBIDDEN` | The key lacks the scope for this operation | | `NOT_FOUND` | The resource does not exist in your account | | `CONFLICT` | Idempotency conflict or insufficient wallet funds | | `RATE_LIMITED` | Over 300 requests per minute; honor `Retry-After` | | `OFFER_UNAVAILABLE`, `CITY_UNAVAILABLE`, `CAPACITY_UNAVAILABLE` | The offer or city cannot be bought right now | | `INVOICE_NOT_PAYABLE` | The invoice is already paid or cancelled, is past due, or its service can no longer be renewed or topped up | | `TRIAL_NOT_ELIGIBLE`, `EMAIL_UNVERIFIED` | The account cannot take this action yet | | `SERVICE_UNAVAILABLE`, `PROVIDER_ERROR`, `PIPE_UNAVAILABLE`, `INTERNAL` | Temporary; retry later, using the same idempotency key for purchases | ## Resellers Reseller keys can act for a managed customer by adding the `customer_id` query parameter or sending an `X-Customer-Id` header, in addition to the operation’s own scope. Reads need `reseller:read`. Proxy and service changes (trusted IPs, projects, password) need `reseller:write`. Creating and paying invoices needs `reseller:purchase`, and on-behalf payments must use `"provider": "wallet"`. A managed customer’s invoice is issued to the reseller. See [the reference](https://docs.trueproxies.com/api/) for the managed customer and wallet operations, and [the Reseller program guide](https://docs.trueproxies.com/reseller-program/) for the wallet limits. ## Related guides - [API reference](https://docs.trueproxies.com/api/) - [Connection and username format](https://docs.trueproxies.com/proxy-instructions/how-to-connect/) - [Trusted IPs](https://docs.trueproxies.com/proxy-instructions/trusted-ips/)