KeelsonDocs
    Judge Mode

    API reference Connections

    Ask the user for a mandate

    POST/v1/connections

    The agent's operator asks its user for a mandate with these limits, as an RFC 8628 device authorization: the user opens verification_uri_complete, compares user_code and approves on Keelson's page with a passkey, lowering any limit. Only a client that linked an operator may ask, and the mandate names that operator. The code expires in 15 minutes and is single use. An app acting for a user with a token they granted it (mandates:request) asks that user only: the request is theirs from the start, so it carries no number to match. The mandate names the app's own operator, or Keelson's hosted operator when the app has none. Through the hosted operator, every app is capped (hosted-cap): one user's open mandates and purchases of the last 180 days with apps whose redirect URIs are not a known host's may not pass HOSTED_CAP_PER_USER_MINOR, and with all such apps HOSTED_CAP_KNOWN_PER_USER_MINOR; every user's funded exposure may not pass HOSTED_CAP_TOTAL_MINOR.

    Headers

    Content-Typeapplication/jsonRequired
    idempotency-keystringRequired
    Idempotency-KeystringRequired
    1 to 255 characters. A retry with the same key returns the first answer.

    Request body

    application/json

    namestringRequired
    reasonstringRequired
    Why the agent asks, in its own words; the user reads it before approving.
    limitsobjectRequired

    Responses

    • 201Show the code and the link to the user, then poll
    • 401No valid access token
    • 403The client linked no operator, and no hosted operator serves it
    • 409The client linked several operators
    • 422The request is invalid, or over the hosted operator's cap (hosted-cap)

    201 response

    device_codestringRequired
    user_codestringRequired
    verification_uristringRequired
    verification_uri_completestringRequired
    expires_inintegerRequired
    intervalintegerRequired
    request_idstringRequired
    The request's id: GET /v1/connections/requests/{id} reads its state without spending the device code.
    match_numberinteger
    Show it beside the link: the user picks it out of three before the request opens, so a link relayed by someone else does not.