Skip to content

Commit

Permalink
Minor doc updates
Browse files Browse the repository at this point in the history
Addresses the following issues:
- Remove Mojaloop mention on payment method page
- Spell out all instances of OP and WM as Open Payments and Web Monetization, respectively
- Minor additions and tweaks to Overview and Open Payments Concepts pages with input from Sarah's blog post

#490

Also took care of updating reference from Open Payments API to Open Payments APIs (plural, no apostrophe)

#456
  • Loading branch information
brad-dow committed Jul 25, 2024
1 parent 36823ce commit 7f126f6
Show file tree
Hide file tree
Showing 13 changed files with 64 additions and 52 deletions.
4 changes: 2 additions & 2 deletions docs/src/content/docs/guides/create-interactive-grant.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package.

### 2. Create and initialize an authenticated Open Payments client

Create an OP authenticated client by providing the following properties:
Create an Open Payments-authenticated client by providing the following properties:

- `walletAddressURL`: your OP-enabled wallet address that your client will use to authenticate itself to one or more authorization servers.
- `walletAddressURL`: your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more authorization servers.
- `privateKey`: the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url.
- `keyId`: the identifier of the private key and the corresponding public key.

Expand Down
6 changes: 3 additions & 3 deletions docs/src/content/docs/guides/make-onetime-payment.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import HttpSig from '/src/partials/http-msg-sig-note.mdx'
import ChunkedSnippet from '/src/components/ChunkedSnippet.astro'
import Ts from '/src/partials/ts-prerequisites.mdx'

The Open Payments (OP) API facilitates multiple uses cases for payments to and from different OP-enabled wallets. In this guide we look at the steps for making a one time payment.
The Open Payments APIs facilitate multiple uses cases for payments to and from different Open Payments-enabled wallets. In this guide we look at the steps for making a one time payment.

Examples of use cases for a one-time payment might be an e-commerce or a money transmitter application.

Expand Down Expand Up @@ -55,9 +55,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package.

### 2. Create an authenticated Open Payments client

Create an OP authenticated client by providing the following properties:
Create an Open Payments-authenticated client by providing the following properties:

- `walletAddressURL` : your OP-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS).
- `walletAddressURL` : your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS).
- `privateKey` : the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private
key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url.
- `keyId` : the identifier of the private key and the corresponding public key.
Expand Down
6 changes: 3 additions & 3 deletions docs/src/content/docs/guides/make-recurring-payments.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import HttpSig from '/src/partials/http-msg-sig-note.mdx'
import ChunkedSnippet from '/src/components/ChunkedSnippet.astro'
import Ts from '/src/partials/ts-prerequisites.mdx'

The Open Payments (OP) API facilitates multiple uses cases for payments to and from different OP-enabled wallets. In this guide we look at the steps for making recurring payments.
The Open Payments APIs facilitate multiple uses cases for payments to and from different Open Payments-enabled wallets. In this guide we look at the steps for making recurring payments.

An example use case for making recurring payments may be a Buy Now Pay Later (BNPL) scheme where a payer purchases a high priced item but pays for it in installments over regularly scheduled intervals.

Expand Down Expand Up @@ -58,9 +58,9 @@ Import `createAuthenticatedClient` from the Open Payments SDK package.

### 2. Create an authenticated Open Payments client

Create an OP authenticated client by providing the following properties:
Create an Open Payments-authenticated client by providing the following properties:

- `walletAddressURL` : your OP-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS).
- `walletAddressURL` : your Open Payments-enabled wallet address that your client will use to authenticate itself to one or more Authorization Servers (AS).
- `privateKey` : the EdDSA-Ed25519 key or preferably the absolute or relative file path to the key that is bound to your wallet address. A public key signed with this private
key must be made available as a public JWK document at `{walletAddressUrl}/jwks.json` url.
- `keyId` : the identifier of the private key and the corresponding public key.
Expand Down
14 changes: 7 additions & 7 deletions docs/src/content/docs/introduction/grants.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import Interactive from '/src/partials/diagram-interactive-grant.mdx'

In Open Payments, a grant indicates a transfer, or delegation, of authorization from a resource owner (RO) to a piece of software. An RO can be a physical person, such as the software’s end user, or a process, such as predefined organizational rules. By delegating authorization, the RO allows the software to access and perform operations on protected resources on the RO’s behalf.

Open Payments leverages the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol'>Grant Negotiation and Authorization Protocol (GNAP)</LinkOut> as the mechanism by which the piece of software, known as a client instance (or client for short), is delegated authorization to use the Open Payments API to interface with supported accounts.
Open Payments leverages the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol'>Grant Negotiation and Authorization Protocol (GNAP)</LinkOut> as the mechanism by which the piece of software, known as a client instance (or client for short), is delegated authorization to use the Open Payments APIs to interface with supported accounts.

## GNAP vs OAuth 2.0

Expand All @@ -29,7 +29,7 @@ GNAP is being developed as the successor to OAuth 2.0 and is designed to fill ma

## Grant authorization servers

An authorization server (AS) grants delegated privileges to a client in the form of access tokens. Access tokens represent a set of access rights and/or attributes granted to the client. With the requisite access token(s), the client can access a resource server’s (RS) Open Payments API and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner.
An authorization server (AS) grants delegated privileges to a client in the form of access tokens. Access tokens represent a set of access rights and/or attributes granted to the client. With the requisite access token(s), the client can access a resource server’s (RS) Open Payments APIs and perform allowed operations, such as creating incoming payments and listing outgoing payments, on behalf of the resource owner.

An AS is uniquely identified by its grant endpoint URI, which is an absolute URI that a client calls to initiate a grant request.

Expand All @@ -41,7 +41,7 @@ A client must generate and add its key to its key registry before requesting a g

## Grant requests

Before a client can access the Open Payments API, it must send a grant request to the AS. The request must contain the type of resource it wants to work with and the action(s) it wants to take on the resource. Resource types include `incoming-payment`, `quote`, and `outgoing-payment`. The available actions depend on type, but examples include `create` and `read`. A successful grant request results in the AS returning one or more access tokens.
Before a client can access the Open Payments APIs, it must send a grant request to the AS. The request must contain the type of resource it wants to work with and the action(s) it wants to take on the resource. Resource types include `incoming-payment`, `quote`, and `outgoing-payment`. The available actions depend on type, but examples include `create` and `read`. A successful grant request results in the AS returning one or more access tokens.

The sequence of requests a client makes when setting up a payment can follow one of the paths below.

Expand All @@ -66,13 +66,13 @@ The sequence of requests a client makes when setting up a payment can follow one

### incoming-payment

A client begins the Open Payments flow by requesting an incoming payment grant from the AS on the _payee_ side. The client can request a single grant to create multiple incoming payments for different OP-enabled accounts as long as each account belongs to the same <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.
A client begins the Open Payments flow by requesting an incoming payment grant from the AS on the _payee_ side. The client can request a single grant to create multiple incoming payments for different Open Payments-enabled accounts as long as each account belongs to the same <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.

Incoming payment grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token.

### quote

After the client receives an incoming payment grant and an incoming payment resource is created on the payee’s account, the client requests a quote grant from the AS on the _payer_ side. The client can request a single grant to create multiple quotes for different OP-enabled accounts as long as each account belongs to the same <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.
After the client receives an incoming payment grant and an incoming payment resource is created on the payee’s account, the client requests a quote grant from the AS on the _payer_ side. The client can request a single grant to create multiple quotes for different Open Payments-enabled accounts as long as each account belongs to the same <Tooltip content="Account servicing entity" client: load><span>ASE</span></Tooltip>.

Quote grants are non-interactive by default, meaning interaction by an individual (typically the client’s end-user) is not required for the AS to issue an access token.

Expand All @@ -86,9 +86,9 @@ After a successful interaction, the client must issue a [Grant Continuation requ

## Open Payments resource servers

A resource server (RS) provides the Open Payments API through which resources can be created or accessed on the server. GNAP doesn’t presume or require a tight coupling between an RS and an AS and it’s increasingly common for the servers to be run and managed separately.
A resource server (RS) provides the Open Payments APIs through which resources can be created or accessed on the server. GNAP doesn’t presume or require a tight coupling between an RS and an AS and it’s increasingly common for the servers to be run and managed separately.

Operations on the API by a client require the client to have a valid access token issued by a <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-16#name-trust-relationships'>trusted AS</LinkOut>. When the client uses its access token to call the RS, the RS examines the token to determine if the token is sufficient for the request. The means by which an RS makes this determination are outside of the scope of Open Payments. If the token is sufficient, the client is given the right to access the operation(s) and resource tied to the token.
Operations on the APIs by a client require the client to have a valid access token issued by a <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-16#name-trust-relationships'>trusted AS</LinkOut>. When the client uses its access token to call the RS, the RS examines the token to determine if the token is sufficient for the request. The means by which an RS makes this determination are outside of the scope of Open Payments. If the token is sufficient, the client is given the right to access the operation(s) and resource tied to the token.

:::note
An open-source implementation of an Open Payments resource server, called <LinkOut href='https://rafiki.dev'>Rafiki</LinkOut>, is currently in development.
Expand Down
8 changes: 4 additions & 4 deletions docs/src/content/docs/introduction/http-signatures.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ title: HTTP message signatures

import { CodeBlock, LinkOut } from '@interledger/docs-design-system'

HTTP message signatures are cryptographic digital signatures used by the Open Payments API to secure HTTP messages exchanged between sender, receiver, or third-party initiating payment systems.
HTTP message signatures are cryptographic digital signatures used by the Open Payments APIs to secure HTTP messages exchanged between sender, receiver, or third-party initiating payment systems.

The Open Payments API implements the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-16#section-7.3.1'> HTTP Signatures </LinkOut> section of the GNAP (Grant Negotiation and Authorization Protocol) specification.
The Open Payments APIs implement the <LinkOut href='https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol-16#section-7.3.1'> HTTP Signatures </LinkOut> section of the GNAP (Grant Negotiation and Authorization Protocol) specification.

## Purpose

The use of digital signatures allow the Open Payments API to address two key aspects of message security:
The use of digital signatures allow the Open Payments APIs to address two key aspects of message security:

- **Authenticity** of any system that requests access to specific resources
- **Integrity** of specific message fields to guard against message tampering
Expand All @@ -19,7 +19,7 @@ Part of how Open Payments-enabled systems control access to protected resources

## Signature algorithms

To generate message signatures, the Open Payments API implements the **Ed25519** variant of the EdDSA (Edwards-curve Digital Signature Algorithm).
To generate message signatures, the Open Payments APIs implement the **Ed25519** variant of the EdDSA (Edwards-curve Digital Signature Algorithm).
EdDSA is an elliptic curve cryptographic algorithm that offers advantages over previous generations of public key cryptography algorithms.

The main advantages for using this digital signature algorithm include:
Expand Down
Loading

0 comments on commit 7f126f6

Please sign in to comment.