API reference

curl -X POST https://winkkey.net/api/admin/api-keys/request \
  -H "Content-Type: application/json" \
  -d '{
    "inviteCode": "WINKKEY-XXXX-XXXX-XXXX",
    "label": "acme-saml",
    "requestedByEmail": "ops@acme.example",
    "reason": "SAML IdP onboarding for federated sign-in pilot."
  }'

{
  "id": "ZmFrZTEyMzQ",
  "label": "acme-saml",
  "keyPrefix": "wkey_a3F2bX…",
  "status": "pending_approval",
  "rawKey": "wkey_a3F2bXc4Z…",
  "createdAt": 1730000000000,
  "requestedByEmail": "ops@acme.example",
  "warning": "Save this key now — it will not be shown again. The key is INACTIVE until an admin approves the request."
}

curl -X POST https://winkkey.net/api/merchant/auth-request \
  -H "Authorization: Bearer wkey_…" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "auth",
    "ttlSeconds": 900,
    "userHintEmail": "user@example.com",
    "callbackUrl": "https://acme.com/cb"
  }'

{
  "rid": "Abc...",
  "kind": "auth",
  "url": "https://winkkey.net/v2/stage/auth/Abc...",
  "expiresAt": 1745800000000
}

curl https://winkkey.net/api/merchant/auth-request/Abc...

{
  "rid": "Abc...",
  "merchantId": "winkkey",
  "env": "stage",
  "status": "consumed",
  "kind": "auth",
  "createdAt": 1745700000000,
  "expiresAt": 1745700900000,
  "consumedAt": 1745700123000,
  "consumedBy": {
    "userId": "...",
    "winkTag": ";stage-...",
    "email": "user@example.com"
  },
  "consumedMethod": "winkkey",
  "resultToken": "eyJ...",
  "winkAccessToken": "eyJ...",
  "winkAccessTokenExpiresAt": 1745700420000,
  "winkAccessTokenStatus": "fresh",
  "winkTokenAvailable": true,
  "callbackUrl": "https://acme.com/cb",
  "userHintEmail": null,
  "forceWinkCloud": false,
  "displayTitle": null,
  "displaySubtext": null,
  "createdBy": { "userId": "...", "email": "operator@you.com" }
}

curl -X DELETE https://winkkey.net/api/merchant/auth-request/Abc... \
  -H "Authorization: Bearer wkey_…"

{ "ok": true, "rid": "Abc...", "status": "failed" }

curl -X POST "https://winkkey.net/api/merchant/auth-request/Abc...?action=renew" \
  -H "Authorization: Bearer wkey_…" \
  -H "Content-Type: application/json" \
  -d '{ "ttlSeconds": 900 }'

{ "ok": true, "rid": "Abc...", "expiresAt": 1745800000000, "status": "pending" }

curl -X POST https://winkkey.net/api/merchant/auth-request/Abc.../send-email \
  -H "Authorization: Bearer wkey_…" \
  -H "Content-Type: application/json" \
  -d '{ "to": "user@example.com" }'

{ "ok": true, "sentTo": "user@example.com" }

{
  "rid": "Abc...",
  "merchantId": "winkkey",
  "env": "stage",
  "status": "pending",
  "expiresAt": 1745800000000,
  "userHintEmail": null,
  "hasCallback": true,
  "userHasWinkKey": null,
  "forceWinkCloud": false,
  "kind": "auth",
  "displayTitle": null,
  "displaySubtext": null
}

curl https://winkkey.net/v2/api/wink/signing-key \
  -H "Authorization: Bearer wkey_..."

{
  "env": "stage",
  "keyId": "23c96f21-7c0e-4a25-a4ba-8b05ab1e86ac",
  "merchantId": "winkkey",
  "pem": "-----BEGIN PRIVATE KEY-----\n..."
}

window.addEventListener('message', (e) => {
  if (e.origin !== 'https://winkkey.net') return;
  if (e.data?.type !== 'winkkey') return;

  switch (e.data.event) {
    case 'auth-link:done':
      // e.data.token       — the result JWT
      // e.data.callbackUrl — null if none was set
      break;
    case 'auth-link:cancelled':
      // user explicitly cancelled (after user-mismatch, etc.)
      break;
    case 'auth-link:mismatch':
      // verifier signed in as the wrong user
      // e.data.expectedEmail / e.data.actualEmail
      break;
    case 'auth-link:invalid':
      // expired, malformed, or generic error
      // e.data.message has detail
      break;
  }
});

curl -X POST https://winkkey.net/api/merchant/vc/issue \
  -H "Authorization: Bearer $WINKKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resultToken": "<jwt-from-auth-link-consume>"
  }'

{
  "vc": "eyJhbGciOiJFZERTQSIs...",
  "format": "vc-jwt",
  "issuer": "did:web:winkkey.net",
  "subject": "did:web:winkkey.net:users:%40alice",
  "issuedAt": 1730000000,
  "expiresAt": 1730000300,
  "winkAccessTokenSource": "vault-snapshot"
}

{
  "iss": "did:web:winkkey.net",
  "sub": "did:web:winkkey.net:users:%40alice",
  "iat": 1730000000,
  "exp": 1730000300,
  "vc": {
    "@context": ["https://www.w3.org/ns/credentials/v2"],
    "type": ["VerifiableCredential", "WinkKeyAuthentication"],
    "issuer": "did:web:winkkey.net",
    "validFrom": "2026-04-28T20:00:00Z",
    "validUntil": "2026-04-28T20:05:00Z",
    "credentialSubject": {
      "id": "did:web:winkkey.net:users:%40alice",
      "winkTag": "@alice",
      "email": "alice@example.com",
      "givenName": "Alice",
      "familyName": "Example",
      "authenticationMethod": "winkkey-passkey",
      "authenticatedAt": "2026-04-28T19:58:00Z",
      "winkSessionFresh": true,
      "winkAccessTokenSource": "vault-snapshot"
    }
  }
}

curl -X POST https://winkkey.net/api/merchant/wink/refresh \
  -H "Authorization: Bearer $WINKKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "winkAccessToken": "<current Wink access token>" }'

{
  "winkAccessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": 1730000300000,
  "source": "vault-refreshed"
}

{
  "error": "needs_wink_reauth",
  "rid": "AKhtBzZgIGOk96zCTCE-FQ",
  "url": "https://winkkey.net/v2/stage/auth/AKhtBzZgIGOk96zCTCE-FQ",
  "detail": "Wink session can't be refreshed on the user's behalf. Hand the URL to the user — they sign in via Wink cloud, our vault picks up a fresh refresh token, and your next /wink/refresh call will succeed."
}