Authentication And Accounts

API Keys#

Every API call carries a Direct API key in the X-API-KEY header, as with Unipile:

curl -sS "https://direct.lempile.com/api/v1/accounts" \
  -H "X-API-KEY: $DIRECT_API_KEY"

• Only the header is read (no api_key query parameter).
• A missing, wrong or revoked key answers 401 with "type": "errors/missing_credentials", on every route, before anything else is checked.
• Direct stores only each key's SHA-256 hash, never the key itself, and never writes a key in a log or an answer.
• Two routes are public, with no key: GET /api/v1/openapi.json (this API's OpenAPI document) and GET /docs (its reference page).

Keys And Workspaces#

Every key belongs to one Lempile workspace, and sees and acts on that workspace's accounts and webhooks only.

• Getting a key. A Lempile admin creates it for your workspace in Lempile's dashboard (Direct → API keys). It starts with ldk_ and is shown once, when it's made: store it as a secret. Ask Lempile for one; each app should have its own. A workspace has at most 50 active keys.
• Revoking a key. A Lempile admin revokes it in the same place. A revoked key answers 401 errors/missing_credentials at once, on every route, for good.
• Accounts. GET /accounts lists your workspace's accounts only, and its total_count and status_counts count those only. Any other account id, whether it belongs to another workspace or doesn't exist, answers exactly the same 404 errors/resource_not_found (title Account not found), on every read, write (dry runs included), account, resync and hosted reconnect route, before any LinkedIn call. A key never learns that another workspace's account exists.
• Webhooks belong to the workspace of the key that created them. GET /webhooks lists your workspace's only; another workspace's webhook id answers 404 to DELETE. Only your workspace's accounts send to your webhooks: an account id of another workspace named in account_ids is kept but never sends, and its name is never answered.
• Hosted auth. A new account connected through your key's link joins your workspace. A reconnect link can only name one of your workspace's accounts (served, or removed earlier); any other answers 404.
• Limits are per account, not per key: two keys using one account share its pacing and daily caps (see Errors And Limits).
• Writes are still turned on per account by Lempile (see Writes Per Account).
• Lempile's own admin keys see every workspace, and are the only keys Direct's internal routes (/api/v1/admin/*, /api/v1/canary) answer; any other key gets 403 errors/insufficient_permissions there. Those routes aren't part of this API.

Account IDs#

An account id is a Lempile account id (a UUID). It names one LinkedIn account connected in Lempile: its own browser, its own proxy, its own LinkedIn session.

curl -sS "https://direct.lempile.com/api/v1/accounts" \
  -H "X-API-KEY: $DIRECT_API_KEY"

{
  "object": "AccountList",
  "items": [
    {
      "object": "Account",
      "type": "LINKEDIN",
      "id": "00000000-0000-4000-8000-0000000000a1",
      "name": "Ada Sender",
      "created_at": "2026-10-28T09:12:44.512Z",
      "connection_params": {
        "im": {
          "id": "ACoAAAbcdefghijklmnop",
          "publicIdentifier": "ada-sender",
          "username": "Ada Sender",
          "premiumId": null,
          "premiumContractId": null,
          "premiumFeatures": ["premium"],
          "organizations": []
        }
      },
      "groups": [],
      "sources": [{ "id": "00000000-0000-4000-8000-0000000000a1_MESSAGING", "status": "OK" }]
    }
  ],
  "cursor": null,
  "total_count": 1,
  "status_counts": { "OK": 1, "CONNECTING": 0, "CREDENTIALS": 0, "STOPPED": 0, "ERROR": 0 }
}

Where the account id goes:

Unlike Unipile, every inbox call names its account, GET /chats/{chat_id} and POST /chats/{chat_id}/messages included: a chat id is LinkedIn's own thread id, which doesn't say which account it belongs to.

An account id Direct doesn't serve (unknown, removed, or another workspace's) answers 404 with "type": "errors/resource_not_found" and title Account not found.

Account Status#

sources[0].status is what Direct has seen, never a guess:

• GET /accounts/{account_id} checks the account first when its status is older than 10 minutes (15 while it's failing): one cheap LinkedIn call through its own session.
• For 5 minutes after LinkedIn signs an account out, every read and write for it answers 401 errors/disconnected_account at once, without asking LinkedIn again (GET /accounts/{account_id} still answers, with CREDENTIALS).
• A change of status sends the account_status webhook (see Webhooks).

Resync#

curl -sS -X POST "https://direct.lempile.com/api/v1/accounts/$ACCOUNT_ID/resync" \
  -H "X-API-KEY: $DIRECT_API_KEY"

GET /accounts/{account_id}/sync (Unipile's form) does the same. Direct drops the session it kept, reads a fresh one from the account's browser, and checks it with LinkedIn:

Removing An Account#

curl -sS -X DELETE "https://direct.lempile.com/api/v1/accounts/$ACCOUNT_ID" \
  -H "X-API-KEY: $DIRECT_API_KEY"

{ "object": "AccountDeleted" }

• Direct stops serving the account, and it stays off across restarts. Its kept session is dropped, and the account_status webhook DELETED is sent.
• The LinkedIn session, the browser and the Lempile account are untouched: Direct never signs anyone out of LinkedIn. provider_session_revoke=true answers 501.
• A removed account can come back through a hosted auth link with type: "reconnect" and its id.

Writes Per Account#

Writes are off by default for each account. Lempile turns them on per account. Until then, a write answers 403:

{
  "title": "Writes off",
  "detail": "This account doesn't write through Lempile Direct.",
  "type": "errors/insufficient_permissions",
  "status": 403
}

Dry runs (?dry_run=true) work for every served account, writes on or off.

Connecting Accounts: Hosted Auth#

POST /api/v1/hosted/accounts/link takes Unipile's body and answers a link to a page Direct serves:

Unipile's other options (disabled_features, disabled_options, proxy, sync_limit, google_scopes, microsoft_scopes, single_use) are accepted and ignored. Direct answers 200 with {"object": "HostedAuthUrl", "url": "https://direct.lempile.com/connect/<token>"}.

What happens next:

1. The person opens the url. A new account will join your key's workspace. The page says "Connect your LinkedIn account" (or "Reconnect") with Cancel and Continue.
2. Continue goes to Lempile's own LinkedIn sign-in, in a real browser on Lempile's servers, with LinkedIn's security checks and codes handled there. Direct never sees the password.
3. Back on Direct, the account is served and its session checked (up to 3 tries, 20 seconds apart, for a fresh browser).
4. When it works: Direct POSTs notify_url with exactly {"status": "CREATION_SUCCESS" | "RECONNECTED", "account_id", "name"} (retried like a webhook), sends the account_status webhooks, and redirects (303) to success_redirect_url.
5. A cancel, a failed sign-in or a session that doesn't work redirects to failure_redirect_url. A reconnect that comes back with a different account fails.

Notes:

• The link's token holds only a random id and its expiry. The redirect and notify URLs stay on Direct's server, encrypted, and never appear in a URL.
• An expired link shows "This link has expired" (410). The way back from the sign-in stays open 30 minutes past the link's expiry, for a sign-in that took long.
• One link starts at most 5 sign-in attempts. A reconnect keeps Lempile's own limit (3 failed attempts in 6 hours).
• notify_url gets no extra header: put your own secret in the URL and check it.
• Direct never signs anyone in or out of LinkedIn itself: the sign-in is Lempile's, in the account's own browser.