diff --git a/packages/auth/src/openapi/specs/id-provider.yaml b/packages/auth/src/openapi/specs/id-provider.yaml index d8ab1937f7..4e43f7944f 100644 --- a/packages/auth/src/openapi/specs/id-provider.yaml +++ b/packages/auth/src/openapi/specs/id-provider.yaml @@ -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: tech@interledger.org servers: - - url: 'https://openpayments.guide/auth' + - url: 'https://openpayments.dev/auth' tags: - name: front-channel description: Redirect URLs @@ -19,7 +19,7 @@ tags: paths: '/interact/{id}/{nonce}': get: - summary: Start user interaction + summary: Start user interaction session responses: '302': content: @@ -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 @@ -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': @@ -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 @@ -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 @@ -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 @@ -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 @@ -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}': @@ -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 @@ -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: diff --git a/packages/backend/src/openapi/specs/webhooks.yaml b/packages/backend/src/openapi/specs/webhooks.yaml index d775db1bcc..22c2a60212 100644 --- a/packages/backend/src/openapi/specs/webhooks.yaml +++ b/packages/backend/src/openapi/specs/webhooks.yaml @@ -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: tech@interledger.org servers: @@ -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: @@ -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 diff --git a/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx b/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx index 47cd4b7cac..fdc457bd23 100644 --- a/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/wallet-addresses.mdx @@ -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 @@ -84,12 +83,12 @@ We strongly recommend you store at least the `walletAddress.id` in your internal
-| 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 |
@@ -194,11 +193,11 @@ Open Payments -| 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 | @@ -232,3 +231,57 @@ Additionally, the request must contain the `walletAddressId` of the wallet addre ``` + +## 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. + + + +```graphql +mutation RevokeWalletAddressKey($input: RevokeWalletAddressKeyInput!) { + revokeWalletAddressKey(input: $input) { + walletAddressKey { + id + revoked + walletAddressId + createdAt + } + } +} +``` + + + +#### Example + + + +```json +{ + "input": { + "id": "e7532552-cff9-4ffe-883e-56613d3ae611" + } +} +``` + + + + + +```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" + } + } + } +} +``` + + \ No newline at end of file diff --git a/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx b/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx index 6140fc887e..b9e6328114 100644 --- a/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx +++ b/packages/documentation/src/content/docs/integration/requirements/webhook-events.mdx @@ -190,7 +190,7 @@ The first retry is after 10 seconds. Additional retries occur after 20 more seco -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. diff --git a/packages/documentation/src/content/docs/overview/concepts/accounting.mdx b/packages/documentation/src/content/docs/overview/concepts/accounting.mdx index c7430a16a7..9ea2b75982 100644 --- a/packages/documentation/src/content/docs/overview/concepts/accounting.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/accounting.mdx @@ -20,7 +20,7 @@ There is one liquidity account for each of the following resources: - Asset - Peer -- Wallet address (for SPSP/Web Monetization receiving) +- Wallet address - Incoming payment - Outgoing payment @@ -460,47 +460,6 @@ A withdrawal is the act of debiting the liquidity account and crediting the sett #### Payments in the same asset -**Simple Payment Setup Protocol (SPSP) / Web Monetization** - -| Debit Account | Credit Account | -| ---------------- | -------------- | -| Outgoing payment | Wallet address | - -**Example:** Send a Web Monetization Payment of `2 USD` over SPSP to a wallet address. Sender and receiver have wallet addresses at the same Rafiki. - - - - - - - - - - -
USD outgoing payment liquidity acctUSD wallet address liquidity acct
- - - - - - - - - -
DebitCredit
2
- 		- - - - - - - - - -
DebitCredit
2
-
- **Send amount < receive amount** | Debit Account | Credit Account | @@ -685,78 +644,6 @@ A withdrawal is the act of debiting the liquidity account and crediting the sett -**Exchanging currencies in Simple Payment Setup Protocol (SPSP) / Web Monetization** - -| Debit Account | Credit Account | Asset | -| ---------------- | --------------- | ----- | -| Outgoing payment | Asset liquidity | `USD` | -| Asset liquidity | Wallet address | `EUR` | - -**Example:** Outgoing payment for `2 USD`, wallet address receives `1 EUR`. - - - - - - - - - - - - - - - - - - -
USD outgoing payment liquidity acctUSD asset liquidity acct
- - - - - - - - - -
DebitCredit
2
- 		- - - - - - - - - -
DebitCredit
2
-
EUR asset liquidity acctEUR wallet address liquidity acct
- - - - - - - - - -
DebitCredit
1
- 		- - - - - - - - - -
DebitCredit
1
-
- ### Interledger transfer examples In these examples, the sender and receiver do not have wallet addresses at the same Rafiki instance. @@ -921,47 +808,6 @@ Remember that a settlement account will always have a zero or negative balance a -**Same asset in Simple Payment Setup Protocol (SPSP) / Web Monetization** - -| Debit Account | Credit Account | -| -------------- | -------------- | -| Peer liquidity | Wallet address | - -**Example:** A wallet address receives `2 USD` from an ILP payment at a peer's Rafiki instance. - - - - - - - - - - -
USD peer liquidity acctUSD wallet address liquidity acct
- - - - - - - - - -
DebitCredit
2
- 		- - - - - - - - - -
DebitCredit
2
-
- **Cross currency** | Debit Account | Credit Account | Asset | @@ -1034,78 +880,6 @@ Remember that a settlement account will always have a zero or negative balance a -**Cross-currency in Simple Payment Setup Protocol (SPSP) / Web Monetization** - -| Debit Account | Credit Account | Asset | -| --------------- | --------------- | ----- | -| Peer liquidity | Asset liquidity | `USD` | -| Asset liquidity | Wallet address | `EUR` | - -**Example:** A Rafiki instance receives `10 USD` from a peer (peering relationship in USD) to be deposited in a wallet address liquidity account denominated in EUR. The payment is converted to EUR and deposited. - - - - - - - - - - - - - - - - - - -
USD peer liquidity acctUSD asset liquidity acct
- - - - - - - - - -
DebitCredit
2
- 		- - - - - - - - - -
DebitCredit
2
-
EUR asset liquidity acctEUR wallet address liquidity acct
- - - - - - - - - -
DebitCredit
1
- 		- - - - - - - - - -
DebitCredit
1
-
- #### Connector **Same asset**