# Customer verification

> How an agent verifies a customer and threads the conversation token so customer-scoped tools can run.

Some tools work for anyone (a person standing at a station, a first-line card check). Others read a customer's own data and need that customer to be **verified** first. Verification attaches a customer's identity to the conversation, and that identity is carried between calls by a **conversation token**.

## The conversation token

The conversation token is an opaque handle for one conversation. It is how the server remembers who has been verified across a series of tool calls.

- It is returned by `customer-request-verification` and refreshed by `customer-verify`.
- You **thread it back unchanged** on every subsequent call in the conversation.
- It is handled at the transport layer, not as a normal tool argument, so it does not appear in the parameter tables in the [reference](/docs/support-agent-mcp/charge-points). The server reads it and strips it before a tool runs.
- On tools that require a verified customer it is mandatory; on the others it is optional, and some tools enrich their output when it is present (for example `charge-points-status` will tell you whether the most recent authorisation attempt used one of the customer's own tokens).

## The flow

1. **Request a code.** Call `customer-request-verification` with the customer's email or user ID and a channel (`email` or `sms`). It sends a six-digit code (valid for five minutes) and returns a `conversationToken`.
2. **Verify the code.** Call `customer-verify` with the code, threading the token back. On success the conversation is upgraded to authorised and a **refreshed** `conversationToken` is returned. Replace the previous token with this one.
3. **Use customer-scoped tools.** Keep threading the latest token. Tools that require a verified customer now run, scoped to what that customer may see.

```flow
step | customer-request-verification | { conversationToken, expiresAt, … }
note | The customer reads the six-digit code and gives it to the agent.
step | customer-verify (code + token) | { verified: true, conversationToken } (refreshed)
note | The conversation is now authorised. Replace the previous token with this one.
step | charge-points-details / charging-cards-details / … | Runs, scoped to the verified customer, with the latest token threaded.
```

## Lifetime and limits

- The verification **code** expires five minutes after it is sent.
- After a successful verification the **conversation** stays authorised on a rolling 30-minute idle window; keep using it and it stays alive.
- A customer gets up to **five attempts** at the code before the challenge locks out; request a new code to start over.
- If the customer mistyped their email or phone, call `customer-request-verification` again with the same `conversationToken` to reuse the conversation rather than starting a new one.

## Trusted clients: skipping the code

A client that has already established the customer's identity by other means can be granted `customer-authorize`, which attaches a known user to a new authorised conversation **without** a one-time code. Because it bypasses verification, it is off by default and a Road operator must explicitly enable it for the client. Treat it as a trusted-client feature, not a general tool.

## Related tools

The tool signatures for this flow are in the reference under [Customer](/docs/support-agent-mcp/customer): `customer-request-verification`, `customer-verify`, `customer-authorize`, and the account-wide `customer-summary`.