Grant Response

The response from the grant endpoint tells the client what it needs to do next, including if it needs to interact with the user and any tokens that have been issued.

If the transaction can be continued by the client, the AS includes a continue handle in the response as well. This handle is used by the client for any subsequent references to this transaction.

The response can also include handles that the client can use in future transactions in lieu of any of the request sections.

{
    "interaction_url": "https://server.example.com/interact/4CF492MLVMSW9MKMXKHQ",
    "callback_server_nonce": "MBDOFXG4Y5CVJCX821LH",
    "continue": {
        "handle": "80UPRY5NM33OMUKMKSKU",
        "uri": "https://server.example.com/continue",
        "wait": 60
    }
}

Each of these sections is detailed below.

Interaction

Foremost, the AS needs to tell the client what to do next. If the user needs to interact with the AS, it will indicate how the user can do that as described in the interaction section, which could include waiting until polling again.

Tokens and Subject

If the transaction is successful, the result could contain one or more access tokens for use at the resource server as well as some subject data about the end user.

If a subject section is returned by the AS, it contains information about the user currently logged in to the AS. This information should be minimal to avoid privacy and data consistency problems.

Continuation

Both the interaction and poll-wait style responses require the the continue response in order to continue. If a transaction handle is included with the access token response, the client can use this handle to get a new access token in the event the first one expires or is revoked, so long as the transaction handle is still valid. The continue response also includes the URL at which the client needs to make its continuation requests, and can include information about how long the client should wait before trying again.

This handle is used by the client to continue the transaction from its previous state. The value returned by the AS is unique, random, and not reused by the AS. That is to say, an ongoing transaction will be represented by a single handle at a given time, and that handle will change over time. This is used in the continuation request.

Dynamic Handles

Parts of the client's request can be assigned reference identifier handles by the AS so that the client can use these in future requests.

If a display_handle is returned by the AS, the client can use this handle in lieu of the information sent in the display block in the request for future transactions.

If a user_handle is returned by the AS, the client can use this handle in lieu of the user portion of the transaction request to represent the same user in future requests, akin to UMA 2's PCT.

If a key_handle is returned by the AS, the client can use this handle in lieu of the key section of the transaction request to reference the same key presented and proved by the client in this transaction. When presenting such key handles in a future request, the client must still bind the request to the referenced key.

Capabilities

If a capabilities section is sent by the client, the AS parses it and returns an array of all the capabilities that this AS can support for this transaction. This allows the client to dynamically self-configure for the transaction.

This piece is effectively a discovery response, but tied directly to the transaction endpoint. This means the client knows the AS as only its transaction endpoint URL and can get everything else it needs from there.