POST Login

Single-call credentials-mode login for catalogs that require a username/password

Sign in to a catalog that requires credentials, and get back a credential_id you can immediately use with POST /v1/wire/task.

The endpoint:

1. Resolves the catalog by slug
2. Finds-or-creates an identity for you (auto-named from params if you don't supply identity_name)
3. Runs the catalog's login wheel against the supplied params
4. Persists a cookies-only credential (the password is never stored)
5. Returns everything needed to call authenticated actions

The password is discarded after a successful sign-in. Only the issued cookies are stored, encrypted. When the cookies expire (see expires_at), call /login again to mint fresh ones.

For browser-based catalogs (auth_types includes browser_state but not credentials), use the interactive connect flow instead.

Request Body

{
  "catalog_slug": "neb",
  "identity_name": "work-account",
  "params": {
    "email": "alice@example.com",
    "password": "..."
  }
}

Discovering the params shape

Different catalogs require different fields. Always read the schema first:

curl {API_BASE}/catalog/neb \
  -H "X-API-Key: your_api_key"

The response includes login_input_schema — an array of {name, type, required, description} field descriptors. Send exactly those fields in params.

Response

{
  "status": "verified",
  "identity_id": "7c3f1a2b-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "identity_name": "alice@example.com",
  "credential_id": "11111111-2222-3333-4444-555555555555",
  "catalog_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "catalog_slug": "neb",
  "expires_at": "2026-05-29T08:09:23Z"
}

Idempotent re-runs

Calling /login again with the same identity_name (or the same derived name) re-uses the existing identity row and refreshes its credential in place — no duplicate rows accumulate. Pass an explicit identity_name if you want multiple identities for the same catalog under one account (e.g. work + personal).

Error Responses

All errors return JSON of the form { "status": "error", "error": { "code": "...", "message": "...", "missing_fields"?: [...] } }. The wheel's raw error text is never echoed; only the typed code is surfaced.

HTTP 200 with status: "error" is used for "the request was well-formed and the wheel ran, but the sign-in itself didn't complete." Treat any status != "verified" as failure regardless of HTTP code.

Example INVALID_PARAMS response:

{
  "status": "error",
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Missing required login fields: password",
    "missing_fields": ["password"]
  }
}

Code Examples

curl {API_BASE}/login \
  -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_slug": "neb",
    "params": {
      "email": "alice@example.com",
      "password": "your_password"
    }
  }'

import requests

response = requests.post(
    '{API_BASE}/login',
    headers={'X-API-Key': 'your_api_key'},
    json={
        'catalog_slug': 'neb',
        'params': {
            'email': 'alice@example.com',
            'password': 'your_password',
        },
    },
)

data = response.json()
if data['status'] == 'verified':
    credential_id = data['credential_id']
    # Use credential_id with /v1/wire/task
else:
    print(f"Login failed: {data['error']['code']} — {data['error']['message']}")
    if data['error']['code'] == 'INVALID_PARAMS':
        print(f"Missing: {data['error']['missing_fields']}")

const response = await fetch('{API_BASE}/login', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    catalog_slug: 'neb',
    params: {
      email: 'alice@example.com',
      password: 'your_password',
    },
  }),
});

const data = await response.json();
if (data.status === 'verified') {
  const credentialId = data.credential_id;
  // Use credentialId with /v1/wire/task
} else {
  console.error(`Login failed: ${data.error.code} — ${data.error.message}`);
  if (data.error.code === 'INVALID_PARAMS') {
    console.error('Missing:', data.error.missing_fields);
  }
}

Rate limit

10 requests per minute per user (each call triggers a real sign-in run against the target site).

Related

• GET /v1/wire/catalog/{slug} — discover login_input_schema
• GET /v1/wire/identities — list identities + credentials
• POST /v1/wire/task — use the returned credential_id to run an authenticated action