> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # 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](/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. ## OpenAPI ````yaml openapi.json POST /api/v2/platform_connect_sessions openapi: 3.1.0 info: title: Agentcard API version: 2.0.0 description: >- The Agentcard v2 API — connect your users and verify their identity from your own backend. Every call is authenticated with a platform access token minted from your `client_id` + `client_secret`. servers: - url: https://api.agentcard.sh description: >- There is one base URL. Sandbox vs production is decided by the client credential you use, never by the host. security: - platformToken: [] tags: - name: Authentication description: >- Exchange your client credentials for a platform access token, and introspect what a token acts as. - name: Connect description: >- Connect a user to your platform: send a one-time code, verify it, record consent, and keep the connection alive. - name: Identity verification description: >- Verify a connected user's identity: upload their ID, submit any extra fields we ask for, then show a short face scan. - name: Wallet funding description: >- Fund a connected user's wallet from your own UI — request a payment link, relay the phone verification code, and poll until the funds land. - name: Withdrawals description: >- Move money out of a connected user's wallet — to a saved bank account or a crypto address on Base. Transfers are processed manually by the Agentcard team, usually within 1-3 business days. paths: /api/v2/platform_connect_sessions: post: tags: - Platform connect summary: Create a connect session description: >- 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. operationId: platformConnectCreate requestBody: required: true content: application/json: schema: type: object required: - return_url properties: return_url: type: string description: >- 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: type: string maxLength: 512 description: >- Opaque value echoed back on the redirect — bind it to the company's session on your side to prevent CSRF. example: return_url: https://example.com/agentcard/callback state: af0ifjsldkj responses: '201': description: The session, including the hosted `url` to send the company to. content: application/json: schema: type: object properties: id: type: string description: >- Session id (`pcs_…`). Use it to poll status and exchange the code. object: type: string example: platform_connect_session status: type: string enum: - pending - bound - completed - claimed - expired description: >- `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: type: string state: type: string nullable: true description: >- Your opaque passthrough value, echoed on the final redirect. sandbox: type: boolean deprecated: true description: Deprecated spelling of `test_mode`. test_mode: type: boolean description: Inherited from the credential that created the session. connected_organization_id: type: string nullable: true description: >- The connected organization, present once the company completes the flow. created_at: type: string format: date-time completed_at: type: string format: date-time nullable: true expires_at: type: string format: date-time description: The hosted link expires 60 minutes after creation. url: type: string description: The hosted flow URL. Redirect the company here. '400': description: >- Invalid body, unregistered `return_url` (`invalid_return_url`), or authenticated with an API key instead of client credentials (`client_credentials_required`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Your organization is not active (`forbidden`) or doesn't have the platform capability (`platform_not_enabled`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object description: Every v2 error uses the same envelope. properties: error: type: object properties: code: type: string description: A stable, machine-readable string (snake_case). Branch on this. message: type: string description: A human-readable explanation, safe to log. docs: type: string description: A link back to the reference. field_errors: type: object additionalProperties: type: string description: Only on `invalid_fields` — names each field to fix. warnings: type: array items: type: string description: >- Only on document upload errors — actionable feedback safe to show the user. securitySchemes: platformToken: type: http scheme: bearer description: >- 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 `. Tokens live one hour. ````