Skip to content
GitHub

Grant Request

POST
/

Make a new grant request

Request Body

object
access_token
required
object
access
required

A description of the rights associated with this access token.

Array
<= 3 items unique items
One of:
object
type
required

The type of resource request as a string. This field defines which other fields are allowed in the request object.

string
Allowed values: incoming-payment
actions
required

The types of actions the client instance will take at the RS as an array of strings.

Array<string>
unique items
Allowed values: create complete read read-all list list-all
identifier

A string identifier indicating a specific resource at the RS.

string format: uri
client
required

Wallet address of the client instance that is making this request.

When sending a non-continuation request to the AS, the client instance MUST identify itself by including the client field of the request and by signing the request.

A JSON Web Key Set document, including the public key that the client instance will use to protect this request and any continuation requests at the AS and any user-facing information about the client instance used in interactions, MUST be available at the wallet address + /jwks.json url.

If sending a grant initiation request that requires RO interaction, the wallet address MUST serve necessary client display information.

string
interact

The client instance declares the parameters for interaction methods that it can support using the interact field.

object
start
required

Indicates how the client instance can start an interaction.

Array<string>
Allowed values: redirect
finish

Indicates how the client instance can receive an indication that interaction has finished at the AS.

object
method
required

The callback method that the AS will use to contact the client instance.

string
Allowed values: redirect
uri
required

Indicates the URI that the AS will either send the RO to after interaction or send an HTTP POST request.

string format: uri
nonce
required

Unique value to be used in the calculation of the “hash” query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.

string
Examples
{
  "access_token": {
    "access": [
      {
        "type": "outgoing-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "https://ilp.interledger-test.dev/alice",
        "limits": {
          "receiver": "https://ilp.interledger-test.dev/incoming-payments/45a0d0ee-26dc-4c66-89e0-01fbf93156f7",
          "interval": "R12/2019-08-24T14:15:22Z/P1M",
          "debitAmount": {
            "value": "500",
            "assetCode": "USD",
            "assetScale": 2
          }
        }
      }
    ]
  },
  "client": "https://webmonize.com/.well-known/pay",
  "interact": {
    "start": [
      "redirect"
    ],
    "finish": {
      "method": "redirect",
      "uri": "https://webmonize.com/return/876FGRD8VC",
      "nonce": "4edb2194-dbdf-46bb-9397-d5fd57b7c8a7"
    }
  }
}

Responses

200

OK

One of:
object
interact
required
object
redirect
required

The URI to direct the end user to.

string format: uri
finish
required

Unique key to secure the callback.

string
continue
required

If the AS determines that the request can be continued with additional requests, it responds with the continue field.

object
access_token
required

A unique access token for continuing the request, called the “continuation access token”.

object
value
required
string
uri
required

The URI at which the client instance can make continuation requests.

string format: uri
wait

The amount of time in integer seconds the client instance MUST wait after receiving this request continuation response and calling the continuation URI.

integer
Examples
{
  "interact": {
    "redirect": "https://auth.interledger-test.dev/4CF492MLVMSW9MKMXKHQ",
    "finish": "4105340a-05eb-4290-8739-f9e2b463bfa7"
  },
  "continue": {
    "access_token": {
      "value": "33OMUKMKSKU80UPRY5NM"
    },
    "uri": "https://auth.interledger-test.dev/continue/4CF492MLVMSW9MKMXKHQ",
    "wait": 30
  }
}

400

Bad Request

401

Unauthorized

500

Internal Server Error