Bearer Token Authentication

Bearer tokens are an optional alternative to username:password for authenticating to the ProxyMesh API and proxy servers. Each token is an opaque string prefixed with pm_   that you send in an Authorization   or Proxy-Authorization   header. For a comparison with IP authentication and Basic auth, see Comparing Authentication Methods.

Plan Requirements and Limits

Bearer tokens are available on paid ProxyMesh plans. Free trials cannot create bearer tokens. The maximum number of tokens per account depends on your subscription plan:

If you downgrade to a plan that does not support bearer tokens (such as a free trial), all bearer tokens on your account and sub-accounts are deactivated automatically.

Create and Manage Tokens in the Dashboard

From your account dashboard, use the Bearer Tokens section on the right to open Edit Bearer Tokens.

On the Edit Bearer Tokens page you can:

1. Enter an optional Label and optional Expires date (leave blank for no expiration).
2. Click Create Token.
3. Copy the new token from the one-time display panel — it will not be shown again.
4. Delete unused tokens from the token list table.

Sub-accounts can have their own bearer tokens. Click Manage Bearer Tokens from the Edit sub account page.

Manage Tokens via the API

Token management endpoints require HTTP Basic Authorization with your account username and password. Bearer tokens cannot be used to create, list, activate, deactivate, or delete other tokens.

For an interactive endpoint reference, see the OpenAPI spec and Swagger UI for the ProxyMesh API.

See Bearer Tokens in the ProxyMesh API article for full endpoint details. To manage tokens for a sub-account, authenticate as the parent account and pass ?username=<sub-account>   on GET requests or include username   in POST form data where supported.

curl -u username:password -X POST -d "label=production" \
  https://proxymesh.com/api/token/create/

API Requests with Bearer Tokens

For all other API endpoints (sub-accounts, IPs, proxies, geo IPs, and so on), send:

Authorization: Bearer pm_…  

curl -H "Authorization: Bearer pm_YOUR_TOKEN" \
  https://proxymesh.com/api/proxies/

import requests

response = requests.get(
    "https://proxymesh.com/api/proxies/",
    headers={"Authorization": "Bearer pm_YOUR_TOKEN"},
)

Invalid, inactive, or expired tokens return 401  . See API Error Response Messages.

Proxy Requests with Bearer Tokens

For proxy connections, send the token in a Proxy-Authorization   header (preferred). Some clients accept Authorization: Bearer …   instead when they do not support proxy-specific headers.

Do not embed the token in the proxy URL (for example http://pm_token@host:port   is not supported). Use the proxy host and port without credentials, and send the bearer header on the CONNECT   request for HTTPS targets.

curl -x "http://us.proxymesh.com:31280" \
  --proxy-header "Proxy-Authorization: Bearer pm_YOUR_TOKEN" \
  https://example.com/

Bearer tokens work well for HTTPS proxy requests when your client sends the header with the initial CONNECT   method. For background, see Proxy Server Requests over HTTPS.

Sticky IP with Bearer Tokens

To reuse the same outgoing proxy IP across requests without storing the assigned IP yourself, append an ip_hash string after the token in the Proxy-Authorization   header. Use any stable string you choose (for example a session ID). ProxyMesh maps that string to an outgoing IP for up to about five minutes between requests, with the same behavior as Basic auth username:ip_hash:password  .

Format:

Proxy-Authorization: Bearer pm_YOUR_TOKEN:your_ip_hash  

curl -x "http://us.proxymesh.com:31280" \
  --proxy-header "Proxy-Authorization: Bearer pm_YOUR_TOKEN:session-abc123" \
  https://example.com/

Repeat the same your_ip_hash   value on later requests to get the same outgoing IP when it is still available. If that IP is no longer available, ProxyMesh assigns a new one and reuses it for subsequent requests with the same ip_hash. For more background, see Authentication Header String in Proxy Server Requests over HTTPS.

Limitations

• Token management needs your password: Creating and revoking tokens always requires HTTP Basic auth with your account credentials.
• One-time display: Copy each new token when it is created; ProxyMesh stores only a hash and cannot show the value again.
• Proxy cache delay: After you deactivate a token, proxy servers may accept it for up to about five minutes before rejecting it.
• Activate and deactivate via API: The dashboard supports create, list, and delete. Use the API to activate or deactivate a token without deleting it.

Security Recommendations

• Treat bearer tokens like passwords — do not commit them to source control or share them in plain text.
• Use separate tokens per application or environment so you can revoke one without affecting others.
• Set an expiration date when you create a token for temporary access.
• Delete or deactivate tokens you no longer use.