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.

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.

Limitations

• No sticky IP format: Bearer auth does not support the username:ip_hash:password  sticky-IP credential format available with Basic auth.
• 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.