> ## 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.
# Verify the code
> Checks the code the user entered and, on success, connects the user and returns the token pair to store. Completing the code **is** the authorization — there is no separate approval screen.
The returned `access_token` is the **user's connection token**: it acts on behalf of this user (send it as the bearer token to the MCP server to create cards, check balances, and shop as them). It is not the platform token — the endpoints in this reference keep using your platform access token and name the user with `user_id`.
A code can be verified once: a second verify of the same attempt returns `invalid_connect_attempt`.
In **sandbox** the code is always `111111`.
The `access_token` returned here is the **user's connection token** — it acts
on behalf of this user. Send it as the bearer token to the
[MCP server](/companies/mcp/overview) to create cards, check balances, and
shop as them. It is **not** the platform token you send to the endpoints in
this reference — those keep using your
[platform access token](/companies/api/reference/create-access-token) and name
the user with `user_id`.
## OpenAPI
````yaml openapi.json POST /api/v2/connect/verify
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/connect/verify:
post:
tags:
- Connect
summary: Verify the code
description: >-
Checks the code the user entered and, on success, connects the user and
returns the token pair to store. Completing the code **is** the
authorization — there is no separate approval screen.
The returned `access_token` is the **user's connection token**: it acts
on behalf of this user (send it as the bearer token to the MCP server to
create cards, check balances, and shop as them). It is not the platform
token — the endpoints in this reference keep using your platform access
token and name the user with `user_id`.
A code can be verified once: a second verify of the same attempt returns
`invalid_connect_attempt`.
In **sandbox** the code is always `111111`.
operationId: connectVerify
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- connect_id
- code
properties:
connect_id:
type: string
description: The `id` returned by `/connect/start`.
code:
type: string
maxLength: 12
description: >-
The one-time code the user entered. Always `111111` in
sandbox.
example:
connect_id: ca_9f8e7d6c
code: '111111'
responses:
'200':
description: >-
The connection. Store the token pair and `user.id` — every KYC call
names the user by it.
content:
application/json:
schema:
$ref: '#/components/schemas/Connection'
example:
object: connection
access_token: act_1a2b3c…
refresh_token: rct_4d5e6f…
token_type: Bearer
expires_in: 3600
user:
id: user_7g8h9i
email: user@example.com
phone: null
'400':
description: >-
`invalid_request` — missing `connect_id` or `code`.
`invalid_connect_attempt` — the attempt is unknown, already used, or
expired. `client_credentials_required` — the token wasn't minted
from client credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: '`invalid_code` — that code is invalid or expired.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: '`auth_provider_error` — verification failed downstream. Try again.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Connection:
type: object
properties:
object:
type: string
enum:
- connection
access_token:
type: string
description: >-
The user's connection token — store it to act on their behalf. Send
it as the bearer token to the MCP server; never in the
`Authorization` header of these endpoints.
refresh_token:
type: string
description: >-
Use it with `/connect/refresh` to get a new pair before the access
token expires.
token_type:
type: string
enum:
- Bearer
expires_in:
type: integer
description: Seconds until the access token expires (3600 = one hour).
user:
type: object
description: >-
The connected user. Store `id` — every KYC call names the user by
it.
properties:
id:
type: string
email:
type:
- string
- 'null'
description: Set when the user connected by email, otherwise `null`.
phone:
type:
- string
- 'null'
description: Set when the user connected by phone, otherwise `null`.
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.
````