POST Create Identity / Login

Find-or-create an identity and sign in to a catalog in one call — with a password or an entry from a connected vault.

Create-and-sign-in in a single call: this endpoint finds-or-creates an identity for the catalog and signs it in, returning a credential_id you can immediately use with POST /v1/wire/task.

There are two ways to supply the login:

• Classic params — pass the catalog's username/password (and any other login fields) directly.
• Vault locator — pass a source_id + source_ref pointing at an entry in a connected identity source, and Wire reads the login fields from your own vault at sign-in time. No password is typed into Wire. The locator is provider-agnostic: 1Password and Azure Key Vault take the same shape.

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; an explicit identity_name is required when using a locator)
3. Resolves the login fields — from params, or from the vault entry referenced by source_id + source_ref
4. Runs the catalog's login wheel against those fields
5. Persists a cookies-only credential (the password is never stored)
6. 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": "..."
  }
}

identity_name is required when using the locator. With a locator there are no params to auto-derive a name from, so you must pass an explicit identity_name. You also cannot send both params and a locator — pick one.

A locator request body looks like:

{
  "catalog_slug": "neb",
  "identity_name": "work-account",
  "source_id": "f1e2d3c4-0000-0000-0000-000000000000",
  "source_ref": { "entry": { "container": "abcd1234", "key": "wxyz5678" } }
}

The source_ref locator

source_ref says where each login field lives; the catalog's login action schema says what the wheel needs. Wire joins the two — you never state which vault field maps to which login parameter.

(a) One entry supplies every field. The common case, and what the dashboard's identity picker emits:

{ "entry": { "container": "abcd1234", "key": "wxyz5678" } }

container is a container ID from list containers; key is an entry ID from list entries.

(b) Per-field refs. For secrets kept apart — a username and password stored as two separate Key Vault secrets:

{
  "fields": {
    "username": { "container": "https://my-vault.vault.azure.net", "key": "acme-user" },
    "password": { "container": "https://my-vault.vault.azure.net", "key": "acme-pass" }
  }
}

(c) Both. fields overrides specific fields and inherits container / key / version from entry wherever they're omitted — e.g. an Azure secret holding the password, with the username carried in a tag:

{
  "entry":  { "container": "https://my-vault.vault.azure.net", "key": "acme" },
  "fields": { "username": { "property": "tag:username" } }
}

Wire matches the vault's field names to the login action's parameter names, falling back to a small alias table (username ↔ user / login / email, password ↔ pass / secret, and so on). If a required login field can't be resolved, the call fails with SOURCE_FIELD_MISSING and names the fields, so you fix them in one pass.

Each parameter the action declares is resolved in this order:

1. An explicit per-field ref in fields — inheriting container, key and version from entry wherever they're omitted
2. An exact name match inside the entry
3. An alias match, per the table above
4. The entry's own property, applied last so it can never shadow a real name match

A distinct entry is read once per sign-in however many parameters it supplies, so pointing four fields at one item costs one round trip to your vault.

username and email travel together. When one of the pair resolves and the other doesn't, Wire fills in the missing one with the same value — so a login action declaring only email still receives username, and vice versa. Passwords are never duplicated, and this is the only pair.

It exists for wheels whose published schema is narrower than what they actually read: before this endpoint resolved fields from a schema, every sourced login was sent username, email and password regardless, and an action declaring email while indexing username worked precisely because both were always present. Expect to see the extra key when inspecting what a login received.

The pre-canonical 1Password shape — { "vault_id": "...", "item_id": "...", "fields": ["username","password"] } — is still accepted, and credentials bound with it keep working. New integrations should use the shape above.

Discovering the params shape

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

curl https://api.anakin.io/v1/wire/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.

Validation / setup — request rejected before the wheel runs:

Locator-only — the binding was rejected before the wheel ran:

Wheel ran (HTTP 200, status: "error") — the request was well-formed and the wheel ran, but sign-in didn't complete:

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

# (a) classic — username/password in params
curl https://api.anakin.io/v1/wire/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"
    }
  }'

# (b) vault locator — fields resolved from your own vault; identity_name required
curl https://api.anakin.io/v1/wire/login \
  -X POST \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog_slug": "neb",
    "identity_name": "work-account",
    "source_id": "f1e2d3c4-0000-0000-0000-000000000000",
    "source_ref": {
      "entry": { "container": "abcd1234", "key": "wxyz5678" }
    }
  }'

import requests

response = requests.post(
    'https://api.anakin.io/v1/wire/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('https://api.anakin.io/v1/wire/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
• GET /v1/wire/identity-sources/{id}/containers — list containers for the locator
• GET /v1/wire/identity-sources/{id}/containers/{container_id}/entries — list entries for the locator
• POST /v1/wire/task — use the returned credential_id to run an authenticated action
• POST /v1/wire/identity-sources — connect a vault to bind against