Transaction Response

The response from the transaction 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 transaction 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",
    "server_nonce": "MBDOFXG4Y5CVJCX821LH",
    "handle": {
        "value": "80UPRY5NM33OMUKMKSKU",
        "type": "bearer"
    },
    "client_handle": {
        "value": "VBUEOIQA82PBY2ZDJW7Q",
        "type": "bearer"
    },
    "key_handle": {
        "value": "7C7C4AZ9KHRS6X63AJAO",
        "type": "bearer"
    }
}

Each of these sections is detailed below.

Next action

Foremost, the AS needs to tell the client what to do next. This may be getting the user to interact with the AS directly, waiting until polling again, or heading to the resource server to use the token.

Both the interaction and poll-wait style responses require the transaction handle, below. 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 trnasaction handle is still valid.

Transaction Handle

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.

Client Handle

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

Interact Handle

If an interact_handle is returned by the AS, the client can use this handle in lieu of the interact portion of the transaction request in future transactions. However, for a redirect based interaction, as this section includes the state value which is supposed to be unguessable and unique per transaction, this response doesn't make sense in such cases.

User Handle

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.

Resource Handle

If a resource_handle is returned by the AS, the client can use this handle in lieu of the resource portions of the transaction request to request the same set of resources in a future transaction.

Key Handle

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.