Customer verification

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. 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.
  1. 1
    customer-request-verification
    { conversationToken, expiresAt, … }

  2. The customer reads the six-digit code and gives it to the agent.

  3. 2
    customer-verify (code + token)
    { verified: true, conversationToken } (refreshed)

  4. The conversation is now authorised. Replace the previous token with this one.

  5. 3
    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.

The tool signatures for this flow are in the reference under Customer: customer-request-verification, customer-verify, customer-authorize, and the account-wide customer-summary.