Create a quote grant request

The Grant Request API lets you request a grant for quote, outgoing payment, and incoming payment resources.

Before your client can call most of the Open Payments APIs, it must receive a grant from the appropriate authorization server.

The code snippets below let a client request a grant for a quote. The request to the authorization server must indicate the quote access type and the actions the client wants to take at the resource server.

Before you begin

We recommend you create an account on the Interledger test network. Creating an account allows you to test your client against the Open Payments APIs by using an ILP-enabled wallet funded with play money.

Request a quote grant

Authenticated client required

TypeScript/NodeJS

Prerequisites(opens in a new tab)

Initial configuration

If you’re using JavaScript, only do the first step.

1. Add "type": "module" to package.json.

2. Add the following to tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "ES2022"
     }
   }

// Import dependencies
import {
  createAuthenticatedClient,
  isFinalizedGrantWithAccessToken
} from '@interledger/open-payments'

// Initialize client
const client = await createAuthenticatedClient({
  walletAddressUrl: CLIENT_WALLET_ADDRESS,
  privateKey: PRIVATE_KEY_PATH,
  keyId: KEY_ID
})

// Get wallet address information
const walletAddress = await client.walletAddress.get({
  url: WALLET_ADDRESS
})

// Request quote grant
const grant = await client.grant.request(
  {
    url: walletAddress.authServer
  },
  {
    access_token: {
      access: [
        {
          type: 'quote',
          actions: ['create', 'read', 'read-all']
        }
      ]
    }
  }
)

// Check grant state
if (!isFinalizedGrantWithAccessToken(grant)) {
  throw new Error('Expected finalized grant')
}

// Output
console.log('QUOTE_ACCESS_TOKEN =', grant.access_token.value)
console.log('QUOTE_ACCESS_TOKEN_MANAGE_URL = ', grant.access_token.manage)

Rust

Prerequisites(opens in a new tab)

// Import dependencies
use open_payments::client::api::UnauthenticatedResources;
use open_payments::client::AuthenticatedResources;
use open_payments::types::{
    auth::{AccessItem, AccessTokenRequest, GrantRequest, QuoteAction},
    GrantResponse,
};

// Initialize client
// Authenticated client can be also used for unauthenticated resources
let client = create_authenticated_client()?;

// Get wallet address information
let wallet_address_url = get_env_var("WALLET_ADDRESS_URL")?;
let wallet_address = client.wallet_address().get(&wallet_address_url).await?;

// Request quote grant
let grant_request = GrantRequest::new(
    AccessTokenRequest {
        access: vec![AccessItem::Quote {
            actions: vec![QuoteAction::Create, QuoteAction::Read, QuoteAction::ReadAll],
        }],
    },
    None,
);

println!(
    "Grant request JSON: {}",
    serde_json::to_string_pretty(&grant_request)?
);

let response = client
    .grant()
    .request(&wallet_address.auth_server, &grant_request, None)
    .await?;

// Output
match response {
    GrantResponse::WithToken { access_token, .. } => {
        println!("Received access token: {:#?}", access_token.value);
        println!(
            "Received access token manage URL: {:#?}",
            access_token.manage
        );
    }
    GrantResponse::WithInteraction { .. } => {
        unreachable!("Interaction not required for quotes");
    }
}

PHP

Prerequisites(opens in a new tab)

// Import dependencies
use OpenPayments\AuthClient;
use OpenPayments\Config\Config;

// Initialize client
$config = new Config(
    $WALLET_ADDRESS,
    $PRIVATE_KEY,
    $KEY_ID
);
$opClient = new AuthClient($config);

// Get wallet address information
$wallet = $opClient->walletAddress()->get([
    'url' => $config->getWalletAddressUrl()
]);

// Request quote grant
$grant = $opClient->grant()->request(
    [
        'url' => $wallet->authServer
    ],
    [
        'access_token' => [
            'access' => [
                [
                    'type' => 'quote',
                    'actions' => ['create', 'read', 'read-all']
                ]
            ]
        ],
        'client' => $config->getWalletAddressUrl()
    ]
);

// Check grant state
if ($grant instanceof \OpenPayments\Models\PendingGrant) {
    throw new \Error('Expected non-interactive grant');
}

// Output
echo 'QUOTE_ACCESS_TOKEN: ' . $grant->access_token->value . PHP_EOL;
echo 'QUOTE_ACCESS_TOKEN_MANAGE_URL: ' . $grant->access_token->manage . PHP_EOL;

echo 'GRANT OBJECT: ' . PHP_EOL . print_r($grant, true);

Go

Prerequisites(opens in a new tab)

package main

// Import dependencies
import (
  "context"
  "encoding/json"
  "fmt"
  "log"

  op "github.com/interledger/open-payments-go"
  as "github.com/interledger/open-payments-go/generated/authserver"
)

func main() {
  // Initialize client
  client, err := op.NewAuthenticatedClient(WALLET_ADDRESS_URL, PRIVATE_KEY_BASE_64, KEY_ID)
  if err != nil {
    log.Fatalf("Error creating authenticated client: %v\n", err)
  }

  // Get wallet address information
  walletAddress, err := client.WalletAddress.Get(context.TODO(), op.WalletAddressGetParams{
    URL: WALLET_ADDRESS_URL,
  })
  if err != nil {
    log.Fatalf("Error fetching wallet address: %v\n", err)
  }

  // Request quote grant
  quoteAccess := as.AccessQuote{
    Type: as.Quote,
    Actions: []as.AccessQuoteActions{
      as.Create,
      as.Read,
    },
  }
  accessItem := as.AccessItem{}
  if err := accessItem.FromAccessQuote(quoteAccess); err != nil {
    log.Fatalf("Error creating AccessItem: %v\n", err)
  }
  accessToken := as.AccessTokenRequest{
    Access: []as.AccessItem{accessItem},
  }

  var grantRequest as.GrantRequest
  if err := grantRequest.FromGrantRequestWithAccessToken(as.GrantRequestWithAccessToken{AccessToken: accessToken}); err != nil {
    log.Fatalf("Error building grant request: %v\n", err)
  }
  grant, err := client.Grant.Request(context.TODO(), op.GrantRequestParams{
    URL:         *walletAddress.AuthServer,
    RequestBody: grantRequest,
  })
  if err != nil {
    log.Fatalf("Error requesting grant: %v\n", err)
  }

  // Check grant state
  if grant.IsInteractive() {
    log.Fatalf("Expected non-interactive grant")
  }

  // Output
  grantJSON, err := json.MarshalIndent(grant, "", "  ")
  if err != nil {
    log.Fatalf("Error marshaling grant: %v\n", err)
  }
  fmt.Println("GRANT:", string(grantJSON))
  fmt.Println("QUOTE_ACCESS_TOKEN =", grant.AccessToken.Value)
  fmt.Println(
    "QUOTE_ACCESS_TOKEN_MANAGE_URL =",
    grant.AccessToken.Manage,
  )

}

Java

Prerequisites(opens in a new tab)

// Import dependencies
import org.interledger.openpayments.httpclient.OpenPaymentsHttpClient;
import org.interledger.openpayments.IOpenPaymentsClient;

// Initialize client
var client = OpenPaymentsHttpClient.defaultClient(
"WalletAddress",
"PrivateKeyPEM",
"KeyId"
);

// Get wallet address information
var senderWallet = client.walletAddress().get("https://cloudninebank.example.com/customer");

// Request quote grant
var grantRequest = client.auth().grant().quote(senderWallet);

// Output
log.info("QUOTE_GRANT: {}", grantRequest);

.NET

Prerequisites(opens in a new tab)

// Import dependencies
using Microsoft.Extensions.DependencyInjection;
using Newtonsoft.Json;
using OpenPayments.Sdk.Clients;
using OpenPayments.Sdk.Extensions;
using OpenPayments.Sdk.Generated.Auth;
using OpenPayments.Sdk.HttpSignatureUtils;

// Initialize client
var client = new ServiceCollection()
    .UseOpenPayments(opts =>
    {
        opts.UseAuthenticatedClient = true;
        opts.KeyId = CLIENT_ID;
        opts.PrivateKey = KeyUtils.LoadPem(CLIENT_SECRET);
        opts.ClientUrl = new Uri(CLIENT_WALLET_ADDRESS);
    })
    .BuildServiceProvider()
    .GetRequiredService<IAuthenticatedClient>();

// Get wallet address information
var walletAddress = await client.GetWalletAddressAsync(WALLET_ADDRESS);

// Request quote grant
var grant = await client.RequestGrantAsync(
    new RequestArgs { Url = walletAddress.AuthServer },
    new GrantCreateBody
    {
        AccessToken = new AccessToken
        {
            Access =
            [
                new QuoteAccess
                {
                    Actions =
                    [
                        Actions.Create,
                        Actions.Read,
                        Actions.ReadAll,
                    ],
                },
            ],
        },
    }
);

// Check grant state
if (grant.Interact != null) throw new Exception("Expected non-interactive grant");

// Output
Console.WriteLine(JsonConvert.SerializeObject(grant, Formatting.Indented));

References

• Auth server API reference
• Grant negotiation and authorization