Grant Request

POST

/

Make a new grant request

Request Body ^required

One of:

Subject

object

subject

Information about the subject for which the client is requesting information

object

sub_id_formats

required

The formats of subject identifiers that the client can accept

Array<string>

unique items

Allowed values: uri

sub_ids

required

Specific identifiers for the subject for which the client is requesting information

Array<string>

>= 1 items

Access Token

object

access_token

object

access

required

A description of the rights associated with this access token.

Array

<= 3 items unique items

One of:

access-incoming

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

access-outgoing

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: outgoing-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 read read-all list list-all

identifier

required

A string identifier indicating a specific resource at the RS.

string format: uri

limits

Any of:

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

debitAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

receiveAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

access-quote

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: quote

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 read read-all

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"
    }
  }
}

{
  "subject": {
    "sub_id_formats": [
      "uri"
    ],
    "sub_ids": [
      "https://wallet.example.com/alice"
    ]
  },
  "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"
    }
  }
}

{
  "access_token": {
    "access": [
      {
        "type": "incoming-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "http://ilp.interledger-test.dev/bob"
      }
    ]
  },
  "client": "https://webmonize.com/.well-known/pay"
}

Responses

200

OK

One of:

object

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

object

object

access_token

required

A single access token or set of access tokens that the client instance can use to call the RS on behalf of the RO.

object

value

required

The value of the access token as a string. The value is opaque to the client instance. The value SHOULD be limited to ASCII characters to facilitate transmission over HTTP headers within other protocols without requiring additional encoding.

string

manage

required

The management URI for this access token. This URI MUST NOT include the access token value and SHOULD be different for each access token issued in a request.

string format: uri

expires_in

The number of seconds in which the access will expire. The client instance MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time.

integer

access

required

A description of the rights associated with this access token.

Array

<= 3 items unique items

One of:

access-incoming

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

access-outgoing

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: outgoing-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 read read-all list list-all

identifier

required

A string identifier indicating a specific resource at the RS.

string format: uri

limits

Any of:

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

debitAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

object

object

receiver

The URL of the incoming payment that is being paid.

string format: uri

/^(https|http)://(.+)/incoming-payments/(.+)$/

interval

ISO8601 repeating interval

string

receiveAmount

required

All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.

object

value

required

The value is an unsigned 64-bit integer amount, represented as a string.

string format: uint64

assetCode

required

The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.

string

assetScale

required

The scale of amounts denoted in the corresponding asset code.

integer

<= 255

access-quote

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: quote

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 read read-all

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
  }
}

{
  "access_token": {
    "value": "OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
    "manage": "https://auth.interledger-test.dev/token/dd17a202-9982-4ed9-ae31-564947fb6379",
    "expires_in": 3600,
    "access": [
      {
        "type": "incoming-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "https://ilp.interledger-test.dev/bob"
      }
    ]
  },
  "continue": {
    "access_token": {
      "value": "33OMUKMKSKU80UPRY5NM"
    },
    "uri": "https://auth.interledger-test.dev/continue/4CF492MLVMSW9MKMXKHQ"
  }
}

400

Bad Request

One of:

object

object

error

object

description

string

code

string

Allowed values: invalid_request

object

object

error

object

description

string

code

string

Allowed values: invalid_client

401

Unauthorized

object

error

object

description

string

code

string

Allowed values: invalid_client

500

Internal Server Error

object

error

object

description

string

code

string

Allowed values: request_denied