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 siteYour 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
- Build the endpoint described below, on https, reachable from the public internet.
- Allow-list Wire's IP addresses. They are shown when you connect.
- 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_apiand the fieldlogin_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. - 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-testwith an error code (for examplelogin_not_found). Never hand out a real login for it.
- 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>| Param | Meaning |
|---|---|
login | The Login ID set on the identity |
site | The 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) |
nonce | A 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"
}nonceis required and must equal thenonceof 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.usernameandpasswordare what most sites need. Other string fields are passed on too, for sites that ask for more (for exampleemailoraccount_id). Fields that are not strings are dropped.totpis optional: a current 6 to 8 digit code. Never send a TOTP seed or anotpauth://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 status | What Wire does |
|---|---|
| 401 | Marks the source revoked. Nothing signs in until it is reconnected |
| 403 | Refuses the sign-in (SOURCE_FORBIDDEN), e.g. your IP allow-list |
| 5xx | Refuses the sign-in (SOURCE_UNREACHABLE) |
429 with no error code | Refuses the sign-in (SOURCE_THROTTLED) |
| anything else | Refuses 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 code | HTTP | When |
|---|---|---|
SOURCE_BAD_ANSWER | 502 | Your 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_ENABLED | 400 | The 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.
Recommended rules for your endpoint
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 nositeis 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.