Skip to content
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

docs: fixes 3084 #3088

Merged
merged 4 commits into from
Nov 13, 2024
Merged

docs: fixes 3084 #3088

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
a3fca70
docs: fixes 3084
melissahenderson Nov 6, 2024
c884630
docs: update based on feedback
melissahenderson Nov 7, 2024
ba85381
update example response
melissahenderson Nov 12, 2024
8a43c7e
incorporating further wallet address feedback
melissahenderson Nov 12, 2024
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
30 changes: 15 additions & 15 deletions packages/auth/src/openapi/specs/id-provider.yaml
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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 |
melissahenderson marked this conversation as resolved.
Show resolved Hide resolved
| --------- | -------------- | ----------------------------------------------------------------------------- |
| `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
Open in desktop
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
Loading