Rotate an access token

The Rotate Access Token API lets you request a new access token from the authorization server. The new token replaces the existing token and has the same rights and properties. If, for example, an access token expires, a client can request the token be rotated.

All access tokens in Open Payments have a 10-minute lifespan by default. This includes new access tokens issued because of a rotate request.

The code snippets below let an authorized client call a management endpoint to rotate a specified access token.

Before you begin

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

Rotate an access token

Authenticated client required

TypeScript/NodeJS

Prerequisites

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 } from '@interledger/open-payments'

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

// Rotate token
const token = await client.token.rotate({
  url: MANAGE_URL,
  accessToken: ACCESS_TOKEN
})

// Output
console.log('ACCESS_TOKEN =', token.access_token.value)
console.log('MANAGE_URL =', token.access_token.manage)

For TypeScript, run tsx path/to/directory/index.ts. View full TS source

For JavaScript, run node path/to/directory/index.js. View full JS source

Rust

Prerequisites

// Import dependencies
use open_payments::client::AuthenticatedResources;
use open_payments::snippets::utils::{create_authenticated_client, get_env_var, load_env};

// Initialize client
let client = create_authenticated_client()?;

// Rotate access token
let access_token = get_env_var("ACCESS_TOKEN")?;
let token_manage_url = get_env_var("TOKEN_MANAGE_URL")?;

let response = client
    .token()
    .rotate(&token_manage_url, Some(&access_token))
    .await?;

// Output
println!("Rotated access token: {:#?}", response.access_token);

View full source

PHP

Prerequisites

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

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

// Rotate access token
$token = $opClient->token()->rotate(
    [
        'access_token' => $ACCESS_TOKEN,
        'url' => $TOKEN_MANAGE_URL
    ]
);

// Output
echo 'ACCESS_TOKEN: ' . $token->value . PHP_EOL;
echo 'MANAGE_URL: ' . $token->manage . PHP_EOL;

View full source

Go

Prerequisites

package main

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

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

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

  // Rotate access token
  rotatedToken, err := client.Token.Rotate(context.TODO(), op.TokenRotateParams{
    URL:         MANAGE_URL,
    AccessToken: ACCESS_TOKEN,
  })
  if err != nil {
    log.Fatalf("Error rotating access token: %v\n", err)
  }

  // Output
  rotatedTokenJSON, err := json.MarshalIndent(rotatedToken, "", "  ")
  if err != nil {
    log.Fatalf("Error marshaling rotated token: %v\n", err)
  }

  fmt.Println("ROTATED ACCESS TOKEN:", string(rotatedTokenJSON))
}

Java

Prerequisites

// 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 receiverWallet = client.walletAddress().get("https://cloudninebank.example.com/merchant");

// Create grant request
var grantRequest = client.auth().grant().incomingPayment(receiverWallet);

// Rotate grant request
// Auth server will be retrieved from [receiverWallet].
var rotatedGrant = client.auth().rotateToken(receiverWallet, grant.getAccess().getToken(), grantRequest);

// Output
log.info("GRANT: {}", rotatedGrant);

.NET

Prerequisites

// Import dependencies
using Microsoft.Extensions.DependencyInjection;
using OpenPayments.Sdk.Clients;
using OpenPayments.Sdk.Extensions;
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>();

// Rotate token
var token = await client.RotateTokenAsync(
    new AuthRequestArgs { Url = new Uri(MANAGE_URL), AccessToken = ACCESS_TOKEN }
);

// Output
Console.WriteLine($"ACCESS_TOKEN = {token.AccessToken.Value}");
Console.WriteLine($"MANAGE_URL = {token.AccessToken.Manage}");

View full source

References

• API specification