Login API Spec

Build one HTTPS endpoint that hands Wire a login for one sign-in, encrypted so only Wire can read it — the contract your endpoint implements

Wire can sign in to a site with a login that your own system hands out for that one sign-in. You don't give Wire access to your vault and Wire stores no password. When a sign-in starts, Wire calls your endpoint, you answer with the login encrypted to Wire's public key, and Wire forgets it when the job ends.

You build one endpoint. It sits in front of wherever your logins live and decides, sign-in by sign-in, whether to hand one out. It uses the same token, key and answer shape as the Card API, and one source can do both.


How it works

You                                        Wire
 |  1. task or sign-in for a site             |
 |------------------------------------------->|
 |  2. GET <your URL>?login=…&site=…&nonce=…  |
 |<-------------------------------------------|
 |  3. login, encrypted to Wire's public key  |
 |------------------------------------------->|
 |                                            |  4. signs in to the site

Your endpoint is the gate: it can refuse any call it doesn't expect, and you can switch Wire off at any time by revoking the token.


Set up

  1. Build the endpoint described below, on https, reachable from the public internet.
  2. Allow-list Wire's IP addresses. They are shown when you connect.
  3. In the dashboard, open Wire → Identity sources → Connect a vault → Your API. Enter your login endpoint URL and a bearer token you issue to Wire (or connect it through the API with provider card_api and the field login_url). Add a card endpoint URL too if the same source should pay bills. The connect form shows Wire's public key (base64 DER): encrypt every login to it.
  4. Wire checks the connection with one test call (login=connection-test), again on every reconnect or token rotation.

Warning: your endpoint must refuse login=connection-test with an error code (for example login_not_found). Never hand out a real login for it.

  1. Add an identity for a site: pick Your API and type the Login ID, the path your endpoint knows this login by (for example acme/ops). Wire stores only that ID.

Use a separate token, URL and key for staging and production.


The call Wire makes

Made each time Wire signs in with this identity.

GET <your URL>?login=<login ID>&site=<site domain>&nonce=<random>
Authorization: Bearer <token>
ParamMeaning
loginThe Login ID set on the identity
siteThe domain of the site Wire is signing in to, such as acme.com. It comes from Wire's catalog (or, for a Build Studio sign-in, the domain of the site being built), never from the caller, so you can check that this login belongs to this site. Sent on every call Wire makes for a sign-in; it is absent only on the connection test (login=connection-test)
nonceA fresh random string for this call. Put it in the encrypted login (see below)
  • One call per sign-in. A retry or a later sign-in calls again. If your endpoint limits how often a login can be read, allow repeats.
  • Wire waits 15 seconds at most, reads at most 64 KB, and never follows redirects.
  • Wire only connects to public addresses.

Your answer

A login — HTTP 200:

{ "success": true, "data": { "login": "<compact JWE>" } }

login is a compact JWE, alg: RSA-OAEP-256, enc: A256GCM, encrypted to Wire's public key. Any other algorithm is refused. Decrypted, it is:

{
  "nonce": "<the nonce from this call>",
  "username": "ops@acme.com",
  "password": "…",
  "totp": "123456"
}
  • nonce is required and must equal the nonce of the call you are answering. A login with a missing or different nonce is refused, so an answer someone captured can't be played back. Encrypt each answer fresh; never cache one.
  • username and password are what most sites need. Other string fields are passed on too, for sites that ask for more (for example email or account_id). Fields that are not strings are dropped.
  • totp is optional: a current 6 to 8 digit code. Never send a TOTP seed or an otpauth:// link; Wire drops them. A code can expire before it is used if the sign-in waits in a queue, so send the newest one you have.

No login — any other answer.

{ "success": false, "error": "<code>", "message": "<text>" }
Your HTTP statusWhat Wire does
401Marks the source revoked. Nothing signs in until it is reconnected
403Refuses the sign-in (SOURCE_FORBIDDEN), e.g. your IP allow-list
5xxRefuses the sign-in (SOURCE_UNREACHABLE)
429 with no error codeRefuses the sign-in (SOURCE_THROTTLED)
anything elseRefuses the sign-in with SOURCE_REFUSED, and your error code as issuer_code

Wire also refuses a sign-in with its own codes, which never carry issuer_code:

Wire's codeHTTPWhen
SOURCE_BAD_ANSWER502Your answer couldn't be read: a 200 with no login, a web page instead of JSON, a JWE that doesn't decrypt with Wire's key, or a decrypted login with a missing or wrong nonce
SOURCE_NOT_ENABLED400The source has no login URL. Add one by editing the source

Your error code is passed on reduced to lower-case letters, digits and _, 40 characters at most. message is never shown, so keep codes meaningful: login_not_found, wrong_site, login_locked.


What Wire does with the login

  • Holds it in memory for the one sign-in. It is never written to a database, log or result.
  • Signs in to the site and keeps the session, as with any other identity.

None are required by Wire. They keep a leaked token or a wrong call from costing you:

  • Check the site. Hand out a login only for the site it belongs to, and refuse a different site (wrong_site). A call with no site is the connection test: refuse it as an unknown login.
  • Allow-list Wire's IPs and keep the token for this endpoint only.
  • Log each call on your side, so you can see every login Wire read.