Grant Request

Request Body^required

Any of:

with Access Token
with Subject

with Access Token

object

client

required

One of:

Wallet address string (deprecated)

DEPRECATED: This string format of the client wallet address is maintained only for backwards compatibility. Migrate to the object form with jwk or walletAddress.

string format: uri

Directed identity (JWK)

object

jwk

required

Ed25519 Public Key

A JWK representation of an Ed25519 Public Key

object

kid

required

string

alg

required

The cryptographic algorithm family used with the key. The only allowed value is EdDSA.

string

Allowed values: EdDSA

use

string

Allowed values: sig

kty

required

string

Allowed values: OKP

crv

required

The cryptographic curve used with the key. This parameter identifies the elliptic curve (for EC keys) or the Edwards curve (for OKP keys). The only allowed value is Ed25519.

string

Allowed values: Ed25519

x

required

The base64 url-encoded public key.

string

/^[a-zA-Z0-9-_]+$/

interact

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

access_token

required

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:

No amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

Debit amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

debitAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

Receive amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

receiveAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

subject

subject

Information about the subject for which the client is requesting information.

object

sub_ids

required

A list of subject identifiers.

Array<object>

>= 1 items <= 1 items

object

id

required

Specific identifier for the subject for which the client is requesting information.

string

format

required

The format of subject identifier that the client can accept.

string

Allowed values: uri

with Subject

object

client

required

One of:

Wallet address string (deprecated)

DEPRECATED: This string format of the client wallet address is maintained only for backwards compatibility. Migrate to the object form with jwk or walletAddress.

string format: uri

Directed identity (JWK)

object

jwk

required

Ed25519 Public Key

A JWK representation of an Ed25519 Public Key

object

kid

required

string

alg

required

The cryptographic algorithm family used with the key. The only allowed value is EdDSA.

string

Allowed values: EdDSA

use

string

Allowed values: sig

kty

required

string

Allowed values: OKP

crv

required

The cryptographic curve used with the key. This parameter identifies the elliptic curve (for EC keys) or the Edwards curve (for OKP keys). The only allowed value is Ed25519.

string

Allowed values: Ed25519

x

required

The base64 url-encoded public key.

string

/^[a-zA-Z0-9-_]+$/

interact

required

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

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:

No amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

Debit amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

debitAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

Receive amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

receiveAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

subject

required

subject

Information about the subject for which the client is requesting information.

object

sub_ids

required

A list of subject identifiers.

Array<object>

>= 1 items <= 1 items

object

id

required

Specific identifier for the subject for which the client is requesting information.

string

format

required

The format of subject identifier that the client can accept.

string

Allowed values: uri

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

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

{
  "access_token": {
    "access": [
      {
        "type": "incoming-payment",
        "actions": [
          "create",
          "read"
        ],
        "identifier": "http://ilp.interledger-test.dev/bob"
      }
    ]
  },
  "client": {
    "jwk": {
      "kid": "example-key-1",
      "alg": "EdDSA",
      "use": "sig",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo"
    }
  }
}

{
  "subject": {
    "sub_ids": [
      {
        "id": "https://ilp.interledger-test.dev/alice",
        "format": "uri"
      }
    ]
  },
  "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"
    }
  }
}

200

OK

One of:

Pending interaction
Approved

Pending interaction

object

interact

required

interact-response

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

continue

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

Approved

object

access_token

required

access_token

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:

No amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

Debit amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

debitAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

Receive amount limit

object

receiver

Receiver

The URL of the incoming payment that is being paid.

string format: uri

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

interval

Interval

ISO8601 repeating interval

string

receiveAmount

required

amount

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

Asset code

The assetCode is a code that indicates the underlying asset. An ISO4217 currency code should be used whenever possible. The ISO4217 representation of the US Dollar is USD.

string

assetScale

required

Asset scale

The number of decimal places that defines the scale of the smallest divisible unit for the given asset code. It determines how an integer amount is scaled to derive the actual monetary value. For example, USD has an asset scale of 2 with the smallest unit being 0.01. An integer amount of 1000 with an assetCode of USD and assetScale of 2 translates to $10.00.

integer

<= 255

continue

required

continue

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:

Invalid request
Invalid client

Invalid request

object

error

object

description

string

code

string

Allowed values: invalid_request

401

Unauthorized

Invalid client

object

error

object

description

string

code

string

Allowed values: invalid_client

500

Internal Server Error

Request denied

object

error

object

description

string

code

string

Allowed values: request_denied

Grant Request

Request Body required

Examples

Responses

200

Examples

400

401

500

Request Body^required