Sign in

v1

latestOpenAPI 3.1.02026-07-26261466.6 KB
Platform connect

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.

post/api/v2/platform_connect_sessions

Request body

return_urlstring required

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.

statestring

Opaque value echoed back on the redirect — bind it to the company's session on your side to prevent CSRF.

Response

The session, including the hosted url to send the company to.

idstring

Session id (pcs_…). Use it to poll status and exchange the code.

objectstring
status'pending' | 'bound' | 'completed' | 'claimed' | 'expired'

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.

return_urlstring
statestring nullable

Your opaque passthrough value, echoed on the final redirect.

sandboxboolean

Deprecated spelling of test_mode.

test_modeboolean

Inherited from the credential that created the session.

connected_organization_idstring nullable

The connected organization, present once the company completes the flow.

created_atstring date-time
completed_atstring date-time nullable
expires_atstring date-time

The hosted link expires 60 minutes after creation.

urlstring

The hosted flow URL. Redirect the company here.

Example response

{
  "object": "platform_connect_session"
}