Create a connect session
Starts a hosted “Connect with Agentcard” flow for a company you’re onboarding. Redirect the company to the returned url; when they finish, we redirect them to your return_url with a one-time code (plus your state) that you exchange for the connected organization’s API credentials.
Requires client-credentials auth (your client_id + client_secret) and the platform capability on your organization — contact us to enable it. The return_url must exactly match a redirect URI registered on the OAuth client you authenticate with.
Authorizations
A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.
Body
Where we send the company when the flow completes. Must exactly match (origin + path) a redirect URI registered on your OAuth client. https required; http://localhost is allowed in test mode.
Opaque value echoed back on the redirect — bind it to the company's session on your side to prevent CSRF.
512Response
The session, including the hosted url to send the company to.
Session id (pcs_…). Use it to poll status and exchange the code.
"platform_connect_session"
pending → the company hasn't finished the hosted flow. bound → the company picked an organization but hasn't confirmed yet. completed → the code was issued and is ready to exchange. claimed → you already exchanged it. expired → the link lapsed.
pending, bound, completed, claimed, expired Your opaque passthrough value, echoed on the final redirect.
Deprecated spelling of test_mode.
Inherited from the credential that created the session.
The connected organization, present once the company completes the flow.
The hosted link expires 60 minutes after creation.
The hosted flow URL. Redirect the company here.