Repository navigation
Expand file tree
/
Copy pathapi.html
More file actions
224 lines (223 loc) · 24.9 KB
/
Copy pathapi.html
File metadata and controls
224 lines (223 loc) · 24.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Shifter Extension API Reference</title><meta name="description" content="Shifter browser proxy extension for Residential and ISP proxies. Chrome and Firefox setup, location targeting, sticky sessions, privacy, and development."><style>*{box-sizing:border-box}html{scroll-behavior:smooth;color-scheme:light}body{margin:0;background:#ffffff;color:#1f2328;font:16px/1.65 system-ui,-apple-system,sans-serif}header,main,footer{max-width:1040px;margin:auto;padding:26px 40px}header{color:#59636e;font-size:12px;letter-spacing:1.5px;font-weight:600;border-bottom:1px solid #d1d9e0}main{padding-top:20px}h1,h2,h3{color:#1f2328;line-height:1.3}h1{font-size:34px;letter-spacing:-.9px;margin:28px 0 16px}h2{margin-top:42px;padding-bottom:10px;border-bottom:1px solid #d1d9e0;font-size:24px}h3{margin-top:28px;font-size:19px}p{margin:16px 0}p[align=center]{text-align:center}p[align=center] img{display:block;width:100%;max-width:960px;height:auto;margin:0 auto}h1[align=center]{text-align:center}a{color:#0969da;text-underline-offset:3px;text-decoration:none}a:hover{text-decoration:underline}code{font:13px/1.7 ui-monospace,SFMono-Regular,Consolas,monospace;overflow-wrap:anywhere;background:#eff1f3;border-radius:4px;padding:2px 5px}pre{padding:20px;overflow:auto;background:#f6f8fa;border:1px solid #d1d9e0;border-radius:8px}pre code{white-space:pre;overflow-wrap:normal;padding:0;background:none}.table{overflow-x:auto}table{width:100%;border-collapse:collapse;font-size:14px}th,td{padding:12px 14px;border:1px solid #d1d9e0;text-align:left;vertical-align:top}th{background:#f6f8fa;color:#1f2328}tr:nth-child(even){background:#f6f8fa}li{margin:6px 0}footer{border-top:1px solid #d1d9e0;color:#59636e;font-size:13px}h2,h3{scroll-margin-top:18px}@media(max-width:650px){header,main,footer{padding:18px}h1{font-size:27px}table{min-width:540px}}@media print{html{color-scheme:light}body{background:white;color:#172235}header,main,footer{max-width:none;padding:12px}h1,h2,h3,th{color:#172235}h2,h3{break-after:avoid}pre,th,tr:nth-child(even){background:#f1f4f8}a{color:#1756a5}}</style></head><body><main><h1 id="shifter-api-for-the-browser-extension">Shifter API for the browser extension</h1>
<p>All account names, IDs, balances, usernames and credentials below are synthetic examples. They are not customer records.</p>
<p>Everything the extension needs to sign a customer in, show their account and set up their proxy.</p>
<ul><li><strong>Base URL:</strong> <code>https://shifter.io</code></li><li><strong>Format:</strong> JSON over HTTPS. All dates are ISO-8601 in UTC (<code>2026-10-23T08:44:14+00:00</code>). Money is USD. Traffic is in bytes and in decimal GB (1 GB = 1,000,000,000 bytes).</li></ul>
<p>---</p>
<h2 id="1-signing-in-the-api-key">1. Signing in: the API key</h2>
<p>The customer signs in by pasting their <strong>API key</strong>. There is no separate extension login.</p>
<div class="table"><table><tr><th>The customer...</th><th>Tell them to...</th></tr><tr><td>has a Shifter account</td><td>open <strong>https://shifter.io/user/profile</strong>, copy the key from the <strong>API Key</strong> section, and paste it into the extension</td></tr><tr><td>has no account</td><td>create one at <strong>https://shifter.io/login</strong> (email, Google or GitHub), buy or start a plan, then copy the key as above</td></tr></table></div>
<p>Send the key on every request, either way:</p>
<pre><code>Authorization: Bearer <API_KEY> (recommended)
GET /api/v1/user/me?api_token=<API_KEY> (also accepted)</code></pre>
<p>The geo endpoints (section 4) take the same key as <code>X-Api-Key: <API_KEY></code> or <code>?api_key=<API_KEY></code>.</p>
<p><strong>How to treat the key:</strong> - The key gives full access to the account, so treat it like a password. - Store it only in <code>chrome.storage.local</code>, never in logs or analytics. - "Log out" in the extension simply deletes it. - If a call ever returns 401, the key is no longer valid: sign the customer out and ask for the key again.</p>
<h3 id="checking-a-key">Checking a key</h3>
<p>Call <code>GET /api/v1/user/me</code>: - <strong>200:</strong> the key is valid, and you get who is signed in. - <strong>401:</strong> show "Invalid API key" and ask for it again.</p>
<p>---</p>
<h2 id="2-response-format-and-errors">2. Response format and errors</h2>
<p>The <code>/api/v1/user/*</code> endpoints wrap every response like this:</p>
<pre><code>{ "error": null, "code": 200, "data": { ... } }</code></pre>
<div class="table"><table><tr><th>HTTP</th><th>Body</th><th>Meaning</th></tr><tr><td>200</td><td><code>{"error":null,"code":200,"data":{...}}</code></td><td>OK</td></tr><tr><td>401</td><td><code>{"error":"Unauthorized","code":401}</code></td><td>missing or wrong key</td></tr><tr><td>429</td><td>Too Many Attempts</td><td>rate limit hit; wait and retry</td></tr><tr><td>5xx</td><td></td><td>our side; retry later</td></tr></table></div>
<p><strong>Rate limit:</strong> 60 requests per minute per key on <code>/user/me</code>, <code>/user/usage</code> and <code>/user/proxy-config</code>, and 60 per minute per IP on the geo endpoints. The popup only needs one refresh when it opens; please don't poll more often than once a minute.</p>
<p>---</p>
<h2 id="workspace-access-in-the-extension">Workspace access in the extension</h2>
<p>Release dependency: Website PR #2139 must be merged and deployed before workspace plans are available. Deployment confirmation is still pending.</p>
<p>The extension requests <code>GET /api/v1/user/proxy-config?workspaces=all</code> and <code>GET /api/v1/user/memberships?workspaces=all</code> with the user's <code>X-Api-Key</code>. It also retains the existing Bearer header for older deployments. Usage remains <code>GET /api/v1/user/usage</code>, which already includes team plans. All three responses are joined by plan hash; credentials, targets and usage stay specific to that plan.</p>
<p>Only the exact <code>workspaces=all</code> value opts in. Without it, the API retains the existing response. <code>?workspace=<id></code> selects one accessible workspace; an unknown or inaccessible id returns no plans. The extension currently fetches all workspaces and groups them locally.</p>
<p>Opted-in proxy-config adds a top-level <code>workspaces</code> list, including workspaces with no usable plans. Each proxy-config plan and memberships row adds a <code>workspace</code> object:</p>
<pre><code>{ "id": "XyZ12", "name": "Acme Ltd", "role": "viewer", "personal": false }</code></pre>
<ul><li><code>id</code> is the same workspace id used by usage and the <code>workspace</code> filter.</li><li><code>name</code> is Personal for the user's workspace; team names come from the owner’s name, username or email.</li><li><code>role</code> is owner for Personal, or viewer, billing or admin for a team member. All roles can connect.</li><li><code>personal</code> is true only for the user's own workspace.</li></ul>
<p>When team workspaces are available, the plan picker groups by workspace, Personal first, and displays empty workspaces. When Personal is the only workspace, the extension keeps the original ungrouped layout with no Personal heading or workspace suffix, whether it has one plan or several. Product names remain exactly as returned by the API. Home shows the team in parentheses beside the product name, such as Spark (Acme Ltd), and explains that team traffic uses that workspace's plan and wallet. Plan management stays in the Shifter dashboard; viewer and billing roles receive an Open in panel link rather than a Renew action. Older responses without workspace metadata retain the existing plan display.</p>
<h2 id="3-endpoints">3. Endpoints</h2>
<h3 id="get-apiv1userme-who-is-signed-in"><code>GET /api/v1/user/me</code>: who is signed in</h3>
<p>Use it for the header of the popup ("Hi Demo, $440.50 in your wallet").</p>
<pre><code>{
"error": null, "code": 200,
"data": {
"user_id": 1001,
"username": "demo",
"first_name": "Demo",
"last_name": "User",
"email": "demo@example.invalid",
"wallet_balance": 440.5,
"currency": "USD",
"created_at": "2022-05-04T10:12:00+00:00"
}
}</code></pre>
<p><code>first_name</code> and <code>last_name</code> can be <code>null</code>, so fall back to <code>username</code>.</p>
<p>---</p>
<h3 id="get-apiv1usermemberships-the-customers-plans"><code>GET /api/v1/user/memberships</code>: the customer's plans</h3>
<p>An object keyed by the plan's short id (hash). It includes cancelled plans; use <code>canceled_at</code> and <code>status</code> to decide what to show.</p>
<pre><code>{
"error": null, "code": 200,
"data": {
"DEMO1": {
"name": "demo #DEMO1 - Spark",
"status": "Active",
"color": "success",
"service": "backconnect",
"uri": "backconnect/DEMO1/",
"membership_id": 2001,
"product": "Spark",
"category": "Residential Proxies",
"is_recurring": true,
"is_trial": false,
"created_at": "2026-09-23T08:44:14+00:00",
"expires_at": "2026-10-23T09:09:18+00:00",
"renews_at": "2026-10-23T08:44:14+00:00",
"trial_ends_at": null,
"canceled_at": null
}
}
}</code></pre>
<div class="table"><table><tr><th>Field</th><th>Meaning</th></tr><tr><td><code>product</code></td><td>plan name to show ("Spark", "Business", "50 ISP Proxies"...)</td></tr><tr><td><code>category</code></td><td>product line: "Residential Proxies", "ISP Proxies", "Special Backconnect Proxies", ...</td></tr><tr><td><code>status</code></td><td>human-readable status: "Active", "Active, Recurring", "Active Trial", "Canceled", "Pending Payment", ...</td></tr><tr><td><code>color</code></td><td><code>success</code> (green, OK), <code>warning</code> (amber, needs attention), <code>danger</code> (red, cancelled/expired), <code>info</code></td></tr><tr><td><code>expires_at</code></td><td>the date the plan is paid until</td></tr><tr><td><code>renews_at</code></td><td>next automatic renewal; <code>null</code> when the plan does not renew (one-time or cancelled)</td></tr><tr><td><code>trial_ends_at</code></td><td>only while a free trial is running</td></tr><tr><td><code>canceled_at</code></td><td>set when the customer cancelled; the plan still works until <code>expires_at</code></td></tr></table></div>
<p><strong>What to show:</strong> if <code>renews_at</code> is set, say "Renews <renews_at>"; otherwise say "Expires <expires_at>".</p>
<p>---</p>
<h3 id="get-apiv1userusage-traffic-left-and-wallet"><code>GET /api/v1/user/usage</code>: traffic left and wallet</h3>
<p>Traffic for every live plan, including plans in team workspaces the customer belongs to. Optional <code>?workspace=<id></code> narrows it to one workspace.</p>
<pre><code>{
"error": null, "code": 200,
"data": {
"totals": {
"quota_bytes": 50000000000, "used_bytes": 12500000000, "remaining_bytes": 37500000000, "overage_bytes": 0,
"quota_gb": 50, "used_gb": 12.5, "remaining_gb": 37.5, "overage_gb": 0, "used_percent": 25
},
"workspaces": [
{ "id": "DEMO3", "name": "Personal", "role": "owner", "personal": true, "wallet_balance": 440.5 }
],
"memberships": [
{
"id": "DEMO1",
"plan": "Spark",
"service": "backconnect",
"status": "Active",
"metered": true,
"quota_bytes": 5000000000, "used_bytes": 1250000000, "remaining_bytes": 3750000000, "overage_bytes": 0,
"quota_gb": 5, "used_gb": 1.25, "remaining_gb": 3.75, "overage_gb": 0,
"used_percent": 25,
"resets_at": "2026-10-23T08:44:14+00:00",
"overage_billed": true,
"overage_rate_per_gb": 2,
"wallet_balance": 440.5,
"wallet_covers_gb": 220.25,
"workspace": { "id": "DEMO3", "name": "Personal", "role": "owner", "personal": true }
}
]
}
}</code></pre>
<ul><li><code>memberships[].id</code> is the same short id (hash) as the keys of <code>/user/memberships</code>, so use it to join the two.</li><li><code>metered: false</code> means the plan has no traffic cap to show (ISP lists, some legacy plans, scraping/SERP). All traffic fields are then <code>null</code>, not <code>0</code>; show "Unlimited" or nothing.</li><li><code>resets_at</code> is when the traffic allowance resets (the next billing cycle).</li><li><code>overage_billed: true</code> means traffic over the allowance is charged from the wallet at <code>overage_rate_per_gb</code>, and <code>wallet_covers_gb</code> is how much extra traffic the current wallet balance pays for.</li></ul>
<p>---</p>
<h3 id="get-apiv1userproxy-config-proxy-login-details"><code>GET /api/v1/user/proxy-config</code>: proxy login details</h3>
<p>Everything needed to configure the proxy, for each <strong>live</strong> plan the customer owns that runs on our gateway. Unpaid and not-yet-active plans are not listed, and neither are older product lines, which keep their own endpoints.</p>
<pre><code>{
"error": null, "code": 200,
"data": {
"plans": [
{
"membership_id": 2001,
"hash": "DEMO1",
"product": "Spark",
"status": "Active",
"protocol": "http",
"type": "residential",
"pool": "full",
"pool_label": "Full Geo",
"host": "p.shifter.io",
"port": 443,
"entry_points": [
{ "key": "auto", "host": "p.shifter.io", "city": null, "region": "Automatic" },
{ "key": "fra", "host": "fra.p.shifter.io", "city": "Frankfurt", "region": "Europe" },
{ "key": "ams", "host": "ams.p.shifter.io", "city": "Amsterdam", "region": "Europe" },
{ "key": "lon", "host": "lon.p.shifter.io", "city": "London", "region": "Europe" },
{ "key": "nyc", "host": "nyc.p.shifter.io", "city": "New York", "region": "North America" },
{ "key": "tor", "host": "tor.p.shifter.io", "city": "Toronto", "region": "North America" },
{ "key": "sgp", "host": "sgp.p.shifter.io", "city": "Singapore", "region": "Asia Pacific" },
{ "key": "blr", "host": "blr.p.shifter.io", "city": "Bangalore", "region": "Asia Pacific" },
{ "key": "syd", "host": "syd.p.shifter.io", "city": "Sydney", "region": "Asia Pacific" }
],
"username": "customer-demo",
"password": "XXXXXXXX",
"targeting": { "country": true, "region": true, "city": true, "asn": true, "sticky_session": true },
"username_format": "customer-{username}[-country-{iso2}][-region-{slug}][-city-{slug}][-asn-{number}][-sid-{session_id}][-ttl-{seconds}]"
},
{
"membership_id": 2002,
"hash": "DEMO2",
"product": "4 ISP Proxies",
"status": "Active, Recurring",
"protocol": "http",
"type": "isp",
"host": "isp.shifter.io",
"port": 443,
"password": "XXXXXXXX",
"proxies": [
{ "username": "us-new_york-new_york-as9009-DEMO1", "country": "us", "city": "New York", "asn": 9009 },
{ "username": "ro-bucharest-bucharest-as8708-DEMO2", "country": "ro", "city": "Bucharest", "asn": 8708 }
]
}
]
}
}</code></pre>
<p>An empty <code>plans</code> array means the customer has nothing to connect yet; link them to https://shifter.io/order.</p>
<h4 id="residential-plans-type-residential">Residential plans (<code>"type": "residential"</code>)</h4>
<p>The customer gets one login, and targeting goes <strong>into the username</strong>, dash-separated:</p>
<pre><code>customer-demo any IP, rotates on every request
customer-demo-country-us a US IP
customer-demo-country-us-city-new_york a New York IP
customer-demo-country-us-region-california a California IP
customer-demo-country-de-asn-3320 Deutsche Telekom (AS3320) in Germany
customer-demo-country-us-sid-a1b2c3 sticky: same IP for this session id
customer-demo-country-us-sid-a1b2c3-ttl-600 sticky for 600 seconds (default 120)</code></pre>
<ul><li><strong>Which targeting is allowed:</strong> it depends on the pool, so only offer what <code>targeting</code> marks <code>true</code>:</li></ul>
<p> - <strong>Full Geo:</strong> country, region, city, ASN. - <strong>Country Geo:</strong> country only. - <strong>Non-Geo:</strong> no targeting at all. - <strong>Sticky sessions:</strong> a new <code>sid</code> value means a new IP. Keep the same <code>sid</code> to keep the IP until its <code>ttl</code> runs out. Use letters and digits only. - <strong>Entry point:</strong> <code>host</code> is the gateway the customer picked in the panel; the default, <code>p.shifter.io</code>, connects to the nearest region automatically. Offer <code>entry_points</code> as an "Entry point" choice if you want: a fixed region keeps a sticky session on the same IP even if the customer's network changes location. - <strong>Protocol:</strong> use <strong>HTTP</strong> on port <strong>443</strong> (a plain HTTP proxy, even though the port is 443).</p>
<h4 id="isp-select-plans-type-isp">ISP Select plans (<code>"type": "isp"</code>)</h4>
<ul><li>Each purchased IP has its own username, all sharing the plan <code>password</code>, on <code>isp.shifter.io:443</code>.</li><li>Each IP is a fixed address in a chosen city and ISP, so offer the list and let the customer pick one.</li><li>There's no targeting to build.</li></ul>
<p>---</p>
<h2 id="4-geo-lists-for-the-targeting-dropdowns">4. Geo lists for the targeting dropdowns</h2>
<p>These list the countries, regions, cities and ASNs available, so the customer picks from a list instead of typing slugs. They're plain JSON arrays with no <code>data</code> wrapper, and they take the key as <code>X-Api-Key</code> or <code>?api_key=</code>.</p>
<div class="table"><table><tr><th>Endpoint</th><th>Returns</th></tr><tr><td><code>GET /api/v1/residential/geo/countries</code></td><td><code>[{"code":"us","name":"United States"}, ...]</code></td></tr><tr><td><code>GET /api/v1/residential/geo/regions?country=us</code></td><td><code>[{"slug":"california","name":"California"}, ...]</code></td></tr><tr><td><code>GET /api/v1/residential/geo/cities?country=us&region=new_york</code></td><td><code>[{"slug":"new_york","name":"New York"}, ...]</code> (drop <code>region</code> for every city in the country)</td></tr><tr><td><code>GET /api/v1/residential/geo/asns?country=de</code></td><td><code>[{"asn":3320,"name":"Deutsche Telekom AG"}, ...]</code></td></tr></table></div>
<ul><li><strong>Use the slug:</strong> put the <code>slug</code> (or <code>code</code> / <code>asn</code>) into the username, never the display name.</li><li><strong>How slugs are made:</strong> accents become plain letters, everything is lowercase, and each run of other characters becomes one <code>_</code>. For example <code>São Paulo</code> becomes <code>sao_paulo</code>, <code>Île-de-France</code> becomes <code>ile_de_france</code>, and <code>St. John's</code> becomes <code>st_john_s</code>.</li><li><strong>Cache the lists:</strong> they change rarely. Cache them for a day, per country.</li></ul>
<p>---</p>
<h2 id="5-setting-the-proxy-in-chrome-manifest-v3">5. Setting the proxy in Chrome (Manifest V3)</h2>
<p><code>manifest.json</code>:</p>
<pre><code>{
"manifest_version": 3,
"permissions": ["proxy", "storage", "webRequest", "webRequestAuthProvider"],
"host_permissions": ["https://shifter.io/*", "<all_urls>"]
}</code></pre>
<p><code>host_permissions</code> for <code>https://shifter.io/*</code> lets the extension call the API without cross-site (CORS) restrictions. <code><all_urls></code> is needed to answer the proxy login.</p>
<p>Turning the proxy on (service worker):</p>
<pre><code>async function enableProxy(host, port) {
await chrome.proxy.settings.set({
scope: 'regular',
value: {
mode: 'fixed_servers',
rules: {
singleProxy: { scheme: 'http', host, port }, // e.g. p.shifter.io, 443
bypassList: ['localhost', '127.0.0.1', 'shifter.io', '*.shifter.io']
}
}
});
}
async function disableProxy() {
await chrome.proxy.settings.clear({ scope: 'regular' });
}</code></pre>
<p>Answering the proxy login:</p>
<pre><code>// username = the plan's username plus the chosen targeting, e.g.
// "customer-demo-country-us-sid-a1b2c3"; password from proxy-config.
chrome.webRequest.onAuthRequired.addListener(
(details, callback) => {
if (!details.isProxy) return callback({});
chrome.storage.local.get(['proxyUser', 'proxyPass'], (s) => {
callback({ authCredentials: { username: s.proxyUser, password: s.proxyPass } });
});
},
{ urls: ['<all_urls>'] },
['asyncBlocking']
);</code></pre>
<ul><li><strong>Bypass <code>shifter.io</code>:</strong> keep <code>shifter.io</code> in the bypass list, so the extension can always reach the API even when the proxy has a problem.</li><li><strong>HTTP only:</strong> Chrome can't send a username and password to a SOCKS5 proxy, so use HTTP.</li><li><strong>Checking it works:</strong> with the proxy on, fetch <code>https://ip-info.com/json</code> and show the IP and country the customer now appears from.</li></ul>
<p>---</p>
<h2 id="6-suggested-popup-flow">6. Suggested popup flow</h2>
<ol><li>No key stored: show the sign-in screen with the two cases from section 1.</li><li>Key entered: call <code>/user/me</code>. On 401 show the error; on 200 save the key.</li><li>Overview: call <code>/user/me</code>, <code>/user/memberships</code> and <code>/user/usage</code> together. Show the name, wallet balance, and one card per plan that isn't cancelled, with its status, "Renews/Expires" date and traffic left (from <code>usage</code> by <code>id</code>).</li><li>Connect: call <code>/user/proxy-config</code>, let the customer pick a plan, then targeting (from the geo lists) and an optional sticky session, and switch the proxy on.</li><li>Log out: clear the proxy settings and delete the stored key and credentials.</li></ol>
<p>---</p>
<p>API documentation: https://shifter.io/docs.</p></main></body></html>