---
title: "Create a connect session"
method: POST
path: "/api/v2/platform_connect_sessions"
tags: ["Platform connect"]
---

# Create a connect session

`POST /api/v2/platform_connect_sessions`

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](/companies/api/reference/platform-connect-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](mailto:support@agentcard.sh) to enable it. The `return_url` must exactly match a redirect URI registered on the OAuth client you authenticate with.

## Request body

- object
  - `return_url` string, 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.
  - `state` string — Opaque value echoed back on the redirect — bind it to the company's session on your side to prevent CSRF.

## Response `201`

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

- object
  - `id` string — Session id (`pcs_…`). Use it to poll status and exchange the code.
  - `object` string
  - `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_url` string
  - `state` string, nullable — Your opaque passthrough value, echoed on the final redirect.
  - `sandbox` boolean — Deprecated spelling of `test_mode`.
  - `test_mode` boolean — Inherited from the credential that created the session.
  - `connected_organization_id` string, nullable — The connected organization, present once the company completes the flow.
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `expires_at` string, date-time — The hosted link expires 60 minutes after creation.
  - `url` string — The hosted flow URL. Redirect the company here.

## Other responses

- `400` — Invalid body, unregistered `return_url` (`invalid_return_url`), or authenticated with an API key instead of client credentials (`client_credentials_required`).
- `401` — Missing or invalid bearer token.
- `403` — Your organization is not active (`forbidden`) or doesn't have the platform capability (`platform_not_enabled`).

---

[API](https://skmtc.dev/agentcard/apis/agentcard-api.md) · [All operations](https://skmtc.dev/agentcard/apis/agentcard-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentcard/agentcard-api/revisions/638d12c8303f/schema)