Authentication

Marvel has two credential planes. Keep them straight and everything else follows.

API key — the proxy

A mk_live_… key. Presented as the proxy username at resi.marvel.sh:9000. This is the credential your scrapers and browsers carry.

Session token — the control API

A bearer token from sign-in. Presented as Authorization: Bearer … to api.marvel.sh/v1/* to manage keys, buy bundles, and read usage.

Accounts & sessions

Accounts are email + password. Passwords are hashed with argon2id (salted, slow) and never stored or logged. Sign-in returns a session token you send as a bearer header to the control API. Sign-up and sign-in return an identical 401 for an unknown email and a wrong password — there is no user-enumeration oracle.

1. Create an account — POST /v1/accounts (password must be at least 8 characters):

   curl -X POST https://api.marvel.sh/v1/accounts \
     -H 'Content-Type: application/json' \
     -d '{"email":"you@example.com","password":"a-strong-passphrase"}'
   # 201 { "account_id": 42, "token": "…" }

2. Sign in later — POST /v1/sessions returns a fresh token:

   curl -X POST https://api.marvel.sh/v1/sessions \
     -H 'Content-Type: application/json' \
     -d '{"email":"you@example.com","password":"a-strong-passphrase"}'
   # 200 { "account_id": 42, "token": "…" }

3. Use the token for every control-API call:

   curl https://api.marvel.sh/v1/me -H "Authorization: Bearer $MARVEL_TOKEN"
   # { "account_id": 42, "email": "you@example.com", "created_at": "…" }

Most people never touch these endpoints directly — the dashboard does it for you. They’re here because everything the dashboard does is a public /v1 call you can make yourself.

API keys

An API key is the credential the proxy accepts. Create as many as you need — one per app, environment, or teammate — and revoke any of them without touching the others.

Shown once

The raw key is returned only at creation. Marvel stores only its SHA-256 — we cannot show it to you again, and it never appears in logs. Lost a key? Revoke it and mint a new one.

# Create a key (label is optional, for your own bookkeeping)
curl -X POST https://api.marvel.sh/v1/keys \
  -H "Authorization: Bearer $MARVEL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"label":"prod-scraper"}'
# 201 { "id": 7, "key": "mk_live_xxxxxxxxxxxxxxxx", "prefix": "mk_live_xxxx", "label": "prod-scraper" }

# List your keys (prefixes only — never the raw secret)
curl https://api.marvel.sh/v1/keys -H "Authorization: Bearer $MARVEL_TOKEN"

# Revoke a key by id
curl -X DELETE https://api.marvel.sh/v1/keys/7 -H "Authorization: Bearer $MARVEL_TOKEN"
# 204 No Content

Present the key to the proxy as the username, with your target as the password:

resi.marvel.sh:9000:mk_live_…:country-US

A revoked or unknown key is rejected at CONNECT with 407. The key resolves to your account on every request; it is never echoed back, logged, or carried into the upstream dial.

At a glance

Plane	Credential	Where	Presented as
Proxy	API key (mk_live_…)	resi.marvel.sh:9000	Proxy username
Control API	Session token	api.marvel.sh/v1/*	Authorization: Bearer