Integrate the agent

The administrator gives the developer the <agent>.chokepoint.json file (Agent identity). With it, the agent does two steps: it exchanges the person's token for a Xokepoint token and uses that token in tool calls.

1. The token exchangeCopy Anchor Link

The agent calls the file's token_endpoint with the RFC 8693 grant and authenticates with private_key_jwt (RFC 7523):

POST <token_endpoint>
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
&subject_token=<person token, issued by the IdP>
&subject_token_type=urn:ietf:params:oauth:token-type:access_token
&client_id=<client_id>
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=<JWT signed with private_key>

The client_assertion is a short JWT signed with the file's private_key, with iss and sub equal to the client_id, an aud equal to the file's issuer or token_endpoint, a unique jti and a near exp. The file's kid goes in the JWT header. A jti is accepted once; reusing it fails with invalid_client.

The response carries an access_token of at most 5 minutes. When it expires, the agent exchanges again with a valid person token. A refused exchange answers invalid_client (the key does not match) or invalid_grant (the person token is invalid or expired, or the person did not delegate to the agent), with the Reference code of the refusal in error_description:

{"error":"invalid_grant","error_description":"Reference x4av-75q6."}

Log the code and send it to your security team: Quick incident opens that refusal with its detailed reason. The response never carries the reason.

To give one running instance narrower limits than the agent's policy, add authorization_details to the same request, for example [{"type":"chokepoint_tool_call","server_id":"<server>","tool":"refund_payment","limits":{"max_amount":100}}] (Instance limits). Send it again on every renewal: limits are not remembered between exchanges. Do not send actor_token, audience, resource or scope; the AS refuses them (What the exchange does not accept).

2. The tool callsCopy Anchor Link

The agent uses the server's MCP address in Xokepoint, with the token in the header:

POST /api/v1/mcp/<workspace>/<environment>/<server>
Authorization: Bearer <Xokepoint access_token>
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18

The body is the usual MCP JSON-RPC. A denied call returns as a JSON-RPC access denied error, without execution; the agent should treat it as an answer, not as a network failure (Failure semantics). The error carries the Reference code of the denied call, in the message that harnesses show and in data for programs:

{"jsonrpc":"2.0","id":7,"error":{"code":-32001,"message":"Access denied. Reference bmbo-2573.","data":{"reference":"bmbo-2573"}}}

Log data.reference. With it, Quick incident opens the call and the step that denied it. A tool that was not reviewed answers HTTP 403 tool_unavailable, with reference in the body too.

The IdP token is never used directly in calls. Xokepoint refuses with 401 a token that it did not issue. For a coding harness, which signs in through the browser instead of a key file, see Connect a coding harness.