Client & Authentication

Creating a client

surge-sdk exports a single factory function. Call it with a configuration object, and optionally the surge-stream module:

var surgeSDK    = require("surge-sdk")
var surgeStream = require("surge-stream")

var sdk = surgeSDK({
  endpoint: "https://surge.surge.sh"
}, surgeStream)

Configuration options

The second argument, surgeStream, is the surge-stream module itself—not an instance. When you pass it, the SDK wires up the three streaming methods (publish, encrypt, ssl). If you omit it, those three methods become no-ops that log `surge-stream` not found, so pass it whenever you intend to deploy.

Supplying credentials

The SDK is stateless: every method takes a credentials argument, and nothing is persisted between calls. Credentials can take any of these shapes:

// A token (the usual case)
{ user: "token", pass: "6b1a5b7d…" }

// A bare token string is shorthand for the same thing
"6b1a5b7d…"

// Email and password (only needed to mint a token)
{ user: "you@example.com", pass: "your-password" }

Under the hood, credentials are sent as HTTP Basic auth. username/password keys work as aliases for user/pass.

Getting a token

Exchange an email and password for a long-lived token with sdk.token(). This is the only call that needs a password—everything after it uses the token:

sdk.token({ user: "you@example.com", pass: password }, function(err, creds){
  if (err) return console.error(err)   // err.status === 401 → bad credentials

  // creds is ready to pass to any other method:
  // { user: "token", pass: "6b1a5b7d…" }

  sdk.account(creds, function(err, account){
    console.log("Logged in as " + account.email)
  })
})

Signing in with an email address that has no account yet creates the account—the same behavior as surge login in the CLI. There is no separate registration call.

Where you store the token is up to your application. The Surge CLI writes it to the user's ~/.netrc file (keyed by API host, with 0600 permissions), which is a good convention for command line tools. For CI and server environments, an environment variable is typical.

To send a password reset email, use sdk.reset(email, callback)—no authentication required.

Verifying the account

sdk.account(creds, callback) returns the account object:

{
  "email": "you@example.com",
  "email_verified_at": "2026-05-01T18:22:10.000Z",
  "role": 4,
  "plan": { "name": "Standard" },
  "card": null
}

Use it at startup to validate a stored token: a 401 means the token has expired or been revoked, and you should re-run the token flow.

Status handlers

The defaults option lets you register cross-cutting handlers for specific HTTP status codes—useful for handling authorization failures in one place instead of in every callback:

var sdk = surgeSDK({
  endpoint: "https://surge.surge.sh",
  defaults: {
    403: function(err, response, body){
      console.error("Unauthorized.")
      process.exit(1)
    }
  }
})

Handlers receive (error, response, body) and run before the method's own callback. The SDK itself never writes to stdout, and errors always reach the callback whether or not a handler is registered.