Skip to main content
POST
Connect a LinkedIn Account
Creates an expiring connection intent and returns a hosted LinkedIn login URL. Free. Authenticated with the signed agent proof (x-agent-proof), which the SDKs sign for you. The human opens the URL and signs in (password, SSO, 2FA, whatever their account needs). OneShot is notified when the login completes. Ownership is bound to your agent only after OneShot verifies the account server-side. The redirect the human sees proves nothing on its own.
The url is returned exactly once and is never stored or logged. Hand it to the human directly. It expires in 30 minutes. Open it top-level, because the hosted page cannot solve LinkedIn’s captcha inside an iframe.

Request

string[]
required
The actions you are asking the human to grant: any of read, reply, view_profile, react, invite (comment is reserved). Ask only for what the agent needs. The human sees this list as the scope of what they are delegating.
string
https:// URL the human is sent to after connecting. No embedded credentials.
string
https:// URL on failure.
An agent can have at most 3 connection links open (pending, unexpired) at a time. A fourth returns 409 intent_pending.

Response

Poll the intent

GET /v1/tools/linkedin/connect/{intent_id} (free, proof-signed) returns the intent with status ∈ pending · verifying · completed · failed · expired · cancelled. completed carries the connected account. failed carries a failure_reason:

Reconnect

Reconnect keeps the account and its history while the human re-authenticates. POST /v1/tools/linkedin/accounts/{id}/reconnect issues a hosted link for an existing account, to restore an expired session or to add granted actions while it is still connected. The intent type is reconnect. The human must complete fresh hosted authentication as the same LinkedIn identity. Creating the link or following the browser redirect does not change permissions. Poll the intent until completed confirms server-side verification. requested_actions is the complete desired grant, not just the actions to add. Include existing actions you want to keep. Omit the field to keep the current grant. Changing the set increments grant_version and refreshes the grant timestamp. An unchanged set keeps its version. The account ID, messages, conversations, coverage, and sync progress stay intact, with no new history enumeration. Adding actions preserves queued writes. Removing any action invalidates older queued writes, even if it is added back later. Revoked or deleted upstream accounts still require a new connection. For an account whose complete current grant is read, reply, and view_profile (and no other actions), add invite like this:

Example

Errors