Skip to content

docs: scalar API docs demo #795

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
brad-dow wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs: scalar API docs demo #795

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dbadf3c
feat: replace starlight-openapi with Scalar standalone API pages
brad-dow May 20, 2026
6ee2f85
docs: update API reference links with Scalar deep link anchors
brad-dow May 20, 2026
61d64fe
fix: convert absolute openpayments.dev hrefs to relative paths in guides
brad-dow May 21, 2026
958bc47
fix: exclude /apis/** from starlight-links-validator
brad-dow May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 20 additions & 168 deletions docs/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ import path from 'node:path'
import { fileURLToPath } from 'node:url'
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import starlightOpenAPI from 'starlight-openapi'
import starlightLinksValidator from 'starlight-links-validator'
import starlightFullViewMode from 'starlight-fullview-mode'
import remarkMath from 'remark-math'
Expand Down Expand Up @@ -91,50 +90,10 @@ export default defineConfig({
src: './public/favicon.svg'
},
plugins: [
// Generate the OpenAPI documentation pages.
starlightOpenAPI([
{
base: 'apis/resource-server',
schema:
'../open-payments-specifications/openapi/resource-server.yaml',
sidebar: { label: 'Open Payments' }
},
{
base: 'es/apis/resource-server',
schema:
'../open-payments-specifications/openapi/resource-server.yaml',
sidebar: { label: 'Open Payments' }
},
{
base: 'apis/wallet-address-server',
schema:
'../open-payments-specifications/openapi/wallet-address-server.yaml',
sidebar: { label: 'Wallet Addresses' }
},
{
base: 'es/apis/wallet-address-server',
schema:
'../open-payments-specifications/openapi/wallet-address-server.yaml',
sidebar: { label: 'Wallet Addresses' }
},
{
base: 'apis/auth-server',
schema: '../open-payments-specifications/openapi/auth-server.yaml',
sidebar: { label: 'Open Payments Authorization Server' }
},
{
base: 'es/apis/auth-server',
schema: '../open-payments-specifications/openapi/auth-server.yaml',
sidebar: { label: 'Open Payments Authorization Server' }
}
]),
starlightLinksValidator({
errorOnLocalLinks: false,
errorOnFallbackPages: false,
exclude: [
'/apis/{auth-server,resource-server,wallet-address-server}/**/*',
'/es/apis/{auth-server,resource-server,wallet-address-server}/**/*'
]
exclude: ['/apis/**']
}),
starlightFullViewMode({
leftSidebarEnabled: true,
Expand Down Expand Up @@ -435,142 +394,35 @@ export default defineConfig({
]
},
{
label: 'API specifications',
label: 'API reference',
collapsed: true,
items: [
{
label: 'Wallet address server',
collapsed: true,
items: [
{
label: 'Get wallet address',
link: '/apis/wallet-address-server/operations/get-wallet-address',
badge: { text: 'GET', variant: 'note' }
},
{
label: 'Get keys bound to wallet address',
link: '/apis/wallet-address-server/operations/get-wallet-address-keys',
badge: { text: 'GET', variant: 'note' }
}
]
link: '/apis/wallet-address-server/',
attrs: {
target: '_blank',
rel: 'noopener noreferrer',
'data-icon': 'external'
}
},
{
label: 'Resource server',
collapsed: true,
items: [
{
label: 'Incoming payment',
collapsed: true,
items: [
{
label: 'Create incoming payment',
link: '/apis/resource-server/operations/create-incoming-payment',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'List incoming payments',
link: '/apis/resource-server/operations/list-incoming-payments',
badge: { text: 'GET', variant: 'note' }
},
{
label: 'Get an incoming payment',
link: '/apis/resource-server/operations/get-incoming-payment',
badge: { text: 'GET', variant: 'note' }
},
{
label: 'Complete an incoming payment',
link: '/apis/resource-server/operations/complete-incoming-payment',
badge: { text: 'POST', variant: 'success' }
}
]
},
{
label: 'Outgoing payment',
collapsed: true,
items: [
{
label: 'Create outgoing payment',
link: '/apis/resource-server/operations/create-outgoing-payment',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'List outgoing payments',
link: '/apis/resource-server/operations/list-outgoing-payments',
badge: { text: 'GET', variant: 'note' }
},
{
label: 'Get an outgoing payment',
link: '/apis/resource-server/operations/get-outgoing-payment',
badge: { text: 'GET', variant: 'note' }
},
{
label:
'Get spent amounts for current outgoing payment grant',
link: '/apis/resource-server/operations/get-outgoing-payment-grant',
badge: { text: 'GET', variant: 'note' }
}
]
},
{
label: 'Quote',
collapsed: true,
items: [
{
label: 'Create quote',
link: '/apis/resource-server/operations/create-quote',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'Get a quote',
link: '/apis/resource-server/operations/get-quote',
badge: { text: 'GET', variant: 'note' }
}
]
}
]
link: '/apis/resource-server/',
attrs: {
target: '_blank',
rel: 'noopener noreferrer',
'data-icon': 'external'
}
},
{
label: 'Auth server',
collapsed: true,
items: [
{
label: 'Grants',
collapsed: true,
items: [
{
label: 'Grant request',
link: '/apis/auth-server/operations/post-request',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'Grant continuation request',
link: '/apis/auth-server/operations/post-continue',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'Cancel grant',
link: '/apis/auth-server/operations/delete-continue',
badge: { text: 'DELETE', variant: 'danger' }
}
]
},
{
label: 'Access token',
collapsed: true,
items: [
{
label: 'Rotate access token',
link: '/apis/auth-server/operations/post-token',
badge: { text: 'POST', variant: 'success' }
},
{
label: 'Revoke access token',
link: '/apis/auth-server/operations/delete-token',
badge: { text: 'DELETE', variant: 'danger' }
}
]
}
]
link: '/apis/auth-server/',
attrs: {
target: '_blank',
rel: 'noopener noreferrer',
'data-icon': 'external'
}
}
]
}
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/concepts/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Having progressed through the incoming payment and quote portions of the Open Pa

Open Payments requires outgoing payment grant requests to be interactive. When a grant request is interactive, it means explicit interaction by an individual (typically the client’s user) is a required step in the delegation process.

After a successful interaction, the client must issue a [Grant Continuation request](/apis/auth-server/operations/post-continue) so the authorization server knows to issue an access token.
After a successful interaction, the client must issue a [Grant Continuation request](/apis/auth-server/#tag/grant/POST/continue/%7Bid%7D) so the authorization server knows to issue an access token.

## More about authorization

Expand Down
16 changes: 8 additions & 8 deletions docs/src/content/docs/concepts/op-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ This page provides a high-level look at the API calls and interactions that occu

## Get account details

A client retrieves public details about a recipient's Open Payments-enabled account by issuing a <LinkOut href='/apis/wallet-address-server/operations/get-wallet-address/'>GET request</LinkOut> to the recipient's wallet address. Details include the asset code and scale of the underlying account and the authorization and resource server URLs which the client needs to set up a payment to the recipient.
A client retrieves public details about a recipient's Open Payments-enabled account by issuing a <LinkOut href='/apis/wallet-address-server/#tag/wallet-address/GET/'>GET request</LinkOut> to the recipient's wallet address. Details include the asset code and scale of the underlying account and the authorization and resource server URLs which the client needs to set up a payment to the recipient.

<MermaidWrapper diagramName="get-account-details">

Expand All @@ -42,7 +42,7 @@ A client retrieves public details about a recipient's Open Payments-enabled acco

## Incoming payment

The client first <LinkOut href='/apis/auth-server/operations/post-request'>requests/receives a grant</LinkOut> from the authorization server of the recipient's <Tooltip content="account servicing entity" client:load>ASE</Tooltip> to create an `incoming-payment` resource. The client then sends a request to the ASE's resource server to <LinkOut href='/apis/resource-server/operations/create-incoming-payment/'>create the resource</LinkOut>. When created, the resource server returns unique payment details the client will use to address one or more payments to the recipient.
The client first <LinkOut href='/apis/auth-server/#tag/grant/POST/'>requests/receives a grant</LinkOut> from the authorization server of the recipient's <Tooltip content="account servicing entity" client:load>ASE</Tooltip> to create an `incoming-payment` resource. The client then sends a request to the ASE's resource server to <LinkOut href='/apis/resource-server/#tag/incoming-payment/POST/incoming-payments'>create the resource</LinkOut>. When created, the resource server returns unique payment details the client will use to address one or more payments to the recipient.

<MermaidWrapper diagramName="incoming-payment">

Expand All @@ -64,7 +64,7 @@ The client first <LinkOut href='/apis/auth-server/operations/post-request'>reque

## Quote

The client <LinkOut href='/apis/auth-server/operations/post-request'>requests/receives a grant</LinkOut> from the authorization server of the sender's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip> to create a `quote` resource. The client then sends a request to the resource server to <LinkOut href='/apis/resource-server/operations/create-quote'>create the resource</LinkOut>. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment.
The client <LinkOut href='/apis/auth-server/#tag/grant/POST/'>requests/receives a grant</LinkOut> from the authorization server of the sender's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip> to create a `quote` resource. The client then sends a request to the resource server to <LinkOut href='/apis/resource-server/#tag/quote/POST/quotes'>create the resource</LinkOut>. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment.

<MermaidWrapper diagramName="quote">

Expand All @@ -86,19 +86,19 @@ The client <LinkOut href='/apis/auth-server/operations/post-request'>requests/re

## Outgoing payment

Before an outgoing payment resource can be created on the sender's account, Open Payments requires the client to send an <LinkOut href='/apis/auth-server/operations/post-request'>interactive grant request</LinkOut> to the authorization server of the sender's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.
Before an outgoing payment resource can be created on the sender's account, Open Payments requires the client to send an <LinkOut href='/apis/auth-server/#tag/grant/POST/'>interactive grant request</LinkOut> to the authorization server of the sender's <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.

An interactive grant requires explicit consent be collected from the sender before an access token is issued. While the client must facilitate the interaction, the authorization server and identity provider (IdP) of the sender's ASE are responsible for the interface and collecting consent.

After consent is obtained, the client requests permission to <LinkOut href='/apis/auth-server/operations/post-continue'>continue the grant request</LinkOut> to obtain an access token.
After consent is obtained, the client requests permission to <LinkOut href='/apis/auth-server/#tag/grant/POST/continue/%7Bid%7D'>continue the grant request</LinkOut> to obtain an access token.

:::note[Continue request timing]
For outgoing payments, explicit user consent is required before proceeding with the continuation request. After the user completes their interaction with the identity provider (IdP), they should be redirected back to your app. At this point, you can make the grant continuation request. In scenarios where a user interface isn't available, consider implementing a polling mechanism to check for the completion of the interaction.
:::

<Interactive />

Once an access token is acquired, the client can request the creation of the <LinkOut href='/apis/resource-server/operations/create-outgoing-payment'>outgoing-payment resource</LinkOut>. The setup of the payment is complete and the Open Payments flow ends after the resource is created.
Once an access token is acquired, the client can request the creation of the <LinkOut href='/apis/resource-server/#tag/outgoing-payment/POST/outgoing-payments'>outgoing-payment resource</LinkOut>. The setup of the payment is complete and the Open Payments flow ends after the resource is created.

<MermaidWrapper diagramName="outgoing-payment">

Expand All @@ -118,7 +118,7 @@ Once an access token is acquired, the client can request the creation of the <Li

## Get transaction history

To provide a user with their transaction history, the client can retrieve a list of the user's <LinkOut href='/apis/resource-server/operations/list-incoming-payments/'>incoming (received) payments</LinkOut> and <LinkOut href='/apis/resource-server/operations/list-outgoing-payments/'>outgoing (sent) payments</LinkOut>.
To provide a user with their transaction history, the client can retrieve a list of the user's <LinkOut href='/apis/resource-server/#tag/incoming-payment/GET/incoming-payments'>incoming (received) payments</LinkOut> and <LinkOut href='/apis/resource-server/#tag/outgoing-payment/GET/outgoing-payments'>outgoing (sent) payments</LinkOut>.

<MermaidWrapper diagramName="get-all-transaction-history">

Expand All @@ -136,7 +136,7 @@ To provide a user with their transaction history, the client can retrieve a list

</MermaidWrapper>

Similarly, the client can provide the user with details about a specific <LinkOut href='/apis/resource-server/operations/get-incoming-payment'>incoming</LinkOut> or <LinkOut href='/apis/resource-server/operations/get-outgoing-payment'>outgoing</LinkOut> payment.
Similarly, the client can provide the user with details about a specific <LinkOut href='/apis/resource-server/#tag/incoming-payment/GET/incoming-payments/%7Bid%7D'>incoming</LinkOut> or <LinkOut href='/apis/resource-server/#tag/outgoing-payment/GET/outgoing-payments/%7Bid%7D'>outgoing</LinkOut> payment.

<MermaidWrapper diagramName="get-specific-transaction-history">

Expand Down
Loading
Loading