Skip to content

Commit

Permalink
docs: fixes 3084 (#3088)
Browse files Browse the repository at this point in the history 
* docs: fixes 3084

* docs: update based on feedback

* update example response

* incorporating further wallet address feedback
  • Loading branch information
@melissahenderson
melissahenderson authored Nov 13, 2024
1 parent 5ede3e0 commit be426fa
Show file tree
Hide file tree
Showing 5 changed files with 106 additions and 279 deletions.
30 changes: 15 additions & 15 deletions packages/auth/src/openapi/specs/id-provider.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,11 @@ info:
name: Apache 2.0
identifier: Apache-2.0
summary: Rafiki Authorization Server - Identity Provider Connection
description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the connection between the Rafiki Open Payments Authorization Server and an Identity Provider.'
description: 'The Open Payments APIs are secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the interaction endpoints used between a Rafiki Open Payments authorization server and an identity provider.'
contact:
email: [email protected]
servers:
- url: 'https://openpayments.guide/auth'
- url: 'https://openpayments.dev/auth'
tags:
- name: front-channel
description: Redirect URLs
Expand All @@ -19,7 +19,7 @@ tags:
paths:
'/interact/{id}/{nonce}':
get:
summary: Start user interaction
summary: Start user interaction session
responses:
'302':
content:
Expand Down Expand Up @@ -52,7 +52,7 @@ paths:
in: path
name: nonce
required: true
description: '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.'
description: '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.'
- schema:
type: string
name: clientName
Expand All @@ -65,7 +65,7 @@ paths:
in: query
required: true
description: 'URI of the client that created the grant'
description: 'To start the user interaction for grant approval, this endpoint redirects the user to an Identity provider endpoint for authentication.'
description: 'This endpoint is called by the client to start the user interaction session for grant approval. The endpoint redirects the user to an identity provider endpoint for authentication.'
tags:
- front-channel
'/interact/{id}/{nonce}/finish':
Expand All @@ -91,7 +91,7 @@ paths:
description: Unauthorized
'404':
description: Not Found
description: "To finish the user interaction for grant approval, this endpoint redirects the user to the client's finish url."
description: "This endpoint is called by the identity provider to end the user interaction and redirect the user to the client's finish URL."
parameters:
- schema:
type: string
Expand All @@ -104,12 +104,12 @@ paths:
in: path
name: nonce
required: true
description: '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.'
description: '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.'
tags:
- front-channel
'/grant/{id}/{nonce}':
get:
summary: Lookup Grant
summary: Look up grant information
responses:
'200':
description: OK
Expand All @@ -123,9 +123,9 @@ paths:
state:
description: |-
Interaction state:
* `PENDING` - Awaiting interaction from resource owner (RO)
* `APPROVED` - RO approved interaction
* `DENIED` - RO Rejected interaction
* `PENDING` - Awaiting interaction from resource owner
* `APPROVED` - Resource owner approved interaction
* `DENIED` - Resource owner rejected interaction
type: string
enum:
- PENDING
Expand All @@ -140,7 +140,7 @@ paths:
description: Not Found
operationId: get-grant
description: |
The Identity Provider uses this endpoint to requests the grant details associated with the provided `interactId` on the front-channel. It will then display those details to the user to either accept or deny the grant.
This endpoint is called by the identity provider to get the grant details associated with the `interactId` on the front-channel. The identity provider will display the details to the user to either accept or deny.
parameters:
- schema:
type: string
Expand All @@ -153,7 +153,7 @@ paths:
in: path
name: nonce
required: true
description: '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.'
description: '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.'
tags:
- back-channel
'/grant/{id}/{nonce}/{choice}':
Expand All @@ -169,7 +169,7 @@ paths:
description: Unauthorized
'404':
description: Not Found
description: The Identity Provider uses this endpoint to submit the user's choice regarding accepting or rejecting a grant to Authorization Server.
description: This endpoint is called by the identity provider to communicate the user's choice (acceptance or rejection) to the authorization server.
parameters:
- schema:
type: string
Expand All @@ -182,7 +182,7 @@ paths:
in: path
name: nonce
required: true
description: '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.'
description: '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.'
- schema:
type: string
enum:
Expand Down
46 changes: 23 additions & 23 deletions packages/backend/src/openapi/specs/webhooks.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ openapi: 3.1.0
info:
title: Rafiki Webhooks
version: 1.1.0
description: 'Webhook Events fired by Rafiki'
description: 'Webhook events fired by Rafiki'
contact:
email: [email protected]
servers:
Expand All @@ -11,113 +11,113 @@ webhooks:
incomingPaymentCreated:
post:
requestBody:
description: Notify account servicing entity that an incoming payment was created.
description: Notifies the account servicing entity that an incoming payment was created.
content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Returns a 200 status to indicate that the data was received successfully.
description: Data received successfully
incomingPaymentCompleted:
post:
requestBody:
description: Notify account servicing entity that an incoming payment was completed and funds should now be withdrawn.
description: Notifies the account servicing entity that an incoming payment was completed and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
incomingPaymentExpired:
post:
requestBody:
description: Notify account servicing entity that an incoming payment has expired and funds should now be withdrawn.
description: Notifies the account servicing entity that an incoming payment has expired and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/incomingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentCreated:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment was created and should now be funded.
description: Notifies the account servicing entity that an outgoing payment was created and is awaiting funding.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentCompleted:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment completed. Remaining funds should be withdrawn.
description: Notifies the account servicing entity that an outgoing payment completed and any remaining funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
outgoingPaymentFailed:
post:
requestBody:
description: Notify account servicing entity that an outgoing payment failed and won't be retried. Funds should be withdrawn.
description: Notifies the account servicing entity that an outgoing payment failed, the retry was unsuccessful, and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/outgoingPaymentEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
walletAddressNotFound:
post:
requestBody:
description: Notify account servicing entity to create a wallet address if it can find a corresponding account in their system.
description: Notifies the account servicing entity to create a wallet address for the associated account in their system.
content:
application/json:
schema:
$ref: '#/components/schemas/walletAddressNotFound'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
webMonetization:
post:
requestBody:
description: Notify account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
description: Notifies the account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
content:
application/json:
schema:
$ref: '#/components/schemas/webMonetizationEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
assetLiquidity:
post:
requestBody:
description: Notify account servicing entity that asset liquidity is low.
description: Notifies the account servicing entity that the liquidity for a specific asset is low.
content:
application/json:
schema:
$ref: '#/components/schemas/liquidityEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully
peerLiquidity:
post:
requestBody:
description: Notify account servicing entity that peer liquidity is low.
description: Notifies the account servicing entity that the liquidity for a specific peer is low.
content:
application/json:
schema:
$ref: '#/components/schemas/liquidityEvent'
responses:
'200':
description: Return a 200 status to indicate that the data was received successfully
description: Data was received successfully

components:
schemas:
Expand Down Expand Up @@ -358,10 +358,10 @@ components:
value:
type: string
format: uint64
description: 'The value is an unsigned 64-bit integer amount, represented as a string.'
description: 'An unsigned 64-bit integer amount, represented as a string.'
assetCode:
type: string
description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
description: A code, generally an ISO 4217 currency code where available, representing the underlying asset
assetScale:
type: integer
minimum: 0
Expand Down
79 changes: 66 additions & 13 deletions ...es/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,9 @@ import { CodeBlock } from '@interledger/docs-design-system'
Each payment account belonging to your users (e.g., customers) must have at least one associated wallet address for the account to be able to send and receive payments over Interledger and Open Payments. A wallet address serves as a publicly shareable standardized ID for a payment account.

:::note[Wallet address requirements]

- Your Rafiki instance must be set up for at least one asset before wallet addresses can be created as each wallet address must have an asset assigned to it.
- Wallet address URLs are treated as case-insensitive, meaning that both lowercase and uppercase variations of the same address will be recognized as identical.
:::
:::

## Create wallet addresses

Expand Down Expand Up @@ -84,12 +83,12 @@ We strongly recommend you store at least the `walletAddress.id` in your internal

<div class="overflow-table">

| Variable | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `assetId` | The unique ID of the asset, assigned by Rafiki when the asset was created, that the wallet address's underlying payment account is denominated in |
| `publicName` | The public name associated with the wallet address |
| `url` | The wallet address's case-insensitive URL |
| `additionalProperties` | Optional [additional properties](/apis/graphql/backend/inputobjects/#additionalpropertyinput) associated with the wallet address |
|Variable | Description |
|-------- | ----------- |
| `assetId` | The unique ID of the asset, assigned by Rafiki when the asset was created, that the wallet address's underlying payment account is denominated in |
| `publicName` | The public name associated with the wallet address |
| `url` | The wallet address's case-insensitive URL |
| `additionalProperties` | Optional [additional properties](/apis/graphql/backend/inputobjects/#additionalpropertyinput) associated with the wallet address |

</div>

Expand Down Expand Up @@ -194,11 +193,11 @@ Open Payments <LinkOut href="https://openpayments.dev/apis/wallet-address-server

<div class="overflow-table">

| Parameter | Required value | Description |
| --------- | -------------- | ----------------------------------------------------------------------------- |
| `alg` | `EdDSA` | The algorithm used to generate the key pair |
| `kty` | `OKP` | The key type identifying the cryptographic algorithm family used with the key |
| `crv` | `Ed25519` | The cryptographic curve used with the key |
| Parameter | Required value | Description |
| --------- | -------------- | ----------- |
| `alg` | `EdDSA` | The algorithm used to generate the key pair |
| `kty` | `OKP` | The key type identifying the cryptographic algorithm family used with the key |
| `crv` | `Ed25519` | The cryptographic curve used with the key |

</div>

Expand Down Expand Up @@ -232,3 +231,57 @@ Additionally, the request must contain the `walletAddressId` of the wallet addre
```

</CodeBlock>

## Revoke a wallet address key

Use the `revokeWalletAddressKey` GraphQL mutation to revoke a public key associated with a wallet address. Open Payments requests using this key for request signatures will be denied going forward.

<CodeBlock title='revokeWalletAddressKey mutation'>

```graphql
mutation RevokeWalletAddressKey($input: RevokeWalletAddressKeyInput!) {
revokeWalletAddressKey(input: $input) {
walletAddressKey {
id
revoked
walletAddressId
createdAt
}
}
}
```

</CodeBlock>

#### Example

<CodeBlock title="Example JSON request">

```json
{
"input": {
"id": "e7532552-cff9-4ffe-883e-56613d3ae611"
}
}
```

</CodeBlock>

<CodeBlock title='Example JSON response'>

```json
{
"data": {
"revokeWalletAddressKey": {
"walletAddressKey": {
"id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
"revoked": true,
"walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
"createdAt": "2023-03-03T09:26:41.424Z"
}
}
}
}
```

</CodeBlock>
2 changes: 1 addition & 1 deletion ...ages/documentation/src/content/docs/integration/requirements/webhook-events.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,7 @@ The first retry is after 10 seconds. Additional retries occur after 20 more seco

</Disclosure>

The `incoming_payment.created` event indicates an incoming payment was created. This event is purely informational because, at this point, the incoming payment has not received any funds and no actions around liquidity are required. You can use this event to display upcoming incoming payments to your users.
The `incoming_payment.created` event indicates an incoming payment was created. At this point, the incoming payment has not received any funds.

The incoming payment will either complete or expire.

Expand Down
Loading

0 comments on commit be426fa

Please sign in to comment.