Authentication

Every authenticated request to the Surge API uses HTTP Basic auth. There are two credential forms:

Minting a token

POST /token with email + password credentials returns a long-lived token:

curl -X POST https://surge.surge.sh/token -u you@example.com:password

{
  "email": "you@example.com",
  "token": "6b1a5b7d0f8e4c…"
}

Tokens are valid for three years. Use the token for all subsequent requests:

curl https://surge.surge.sh/account -u token:6b1a5b7d0f8e4c…

This is the same token that surge login stores in your ~/.netrc, and that surge token prints—so for scripting against the API you can simply reuse the CLI's token.

Account creation

There is no separate signup endpoint. Authenticating with an email address that has no account creates the account with that email and password. This is how the CLI's first surge run registers you, and it applies to POST /token as well: mint a token with fresh credentials and you've created an account.

The account object

GET /account returns the authenticated account, including plan and card status:

{
  "email": "you@example.com",
  "email_verified_at": "2026-05-01T18:22:10.000Z",
  "created_at": "2024-01-15T09:30:00.000Z",
  "plan": { "name": "Standard" },
  "card": null
}

A 401 here means the token is expired or revoked—mint a new one.

Email verification

POST /verification (authenticated) sends a verification link to the account's email address:

• 200 { "verified": true } — already verified, nothing sent.
• 201 { "verified": false, "sent": true } — verification email sent.
• 200 { "verified": false, "sent": false, "msg": "…" } — an email was already sent within the last five minutes.

Unverified accounts operate under tighter publish rate limits, so verify early.

Password reset

POST /token/reset/:email (no authentication) sends password reset instructions:

curl -X POST https://surge.surge.sh/token/reset/you@example.com

Always responds 201, whether or not the email matches an account.