Skip to content

Commit 88c34f7

Browse files
hajjimohajjimo
authored
docs: mi/3243/op-grant-revocation (#3359)
* docs: mi/3243/op-grant-revocation - New Open Payments submenu under requirements - Moved IdP and managing wallet address keys management section under the OP submenu - New page for viewing and revoking grants (need to fill in query and mutation input details, and example requests and responses). * docs: mi/3243/op-grant-revocation Fix broken links as a result of moving IdP page to requirements/open-payments * dcos: mi/3243/op-grant-revocation * docs: mi/324/op-grant-revocation resolve merge conflicts * docs: mi/3243/op-grant-revocation * docs: mi/3243/op-grant-revocation Updated styling on GraphQL operations.
1 parent 1cd0790 commit 88c34f7

File tree

8 files changed

+370
-168
lines changed

8 files changed

+370
-168
lines changed

‎packages/documentation/astro.config.mjs‎

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -147,8 +147,22 @@ export default defineConfig({
147147
link: '/integration/requirements/sending-fees'
148148
},
149149
{
150-
label: 'Identity provider (IdP)',
151-
link: '/integration/requirements/idp'
150+
label: 'Open Payments',
151+
collapsed: true,
152+
items: [
153+
{
154+
label: 'Identity provider (IdP)',
155+
link: '/integration/requirements/open-payments/idp'
156+
},
157+
{
158+
label: 'Managing wallet address keys',
159+
link: '/integration/requirements/open-payments/wallet-keys'
160+
},
161+
{
162+
label: 'Viewing and revoking grants',
163+
link: '/integration/requirements/open-payments/grants-revoking'
164+
}
165+
]
152166
}
153167
]
154168
},

‎packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,13 @@ Review the <LinkOut href="https://openpayments.dev/introduction/client-keys/">Op
3838

3939
An identity provider (IdP) is a system or service that manages user authentication, identity information, and consent. When you use your Google Account credentials to “Sign in with Google” on an app or website, for example, Google is acting as your identity provider.
4040

41-
You must integrate with an [IdP](/integration/requirements/idp) when using Rafiki's `auth` service because the Open Payments standard requires interactive outgoing payment _grant_ requests. In an interactive request, there must be explicit interaction by an individual (for example, a client's end-user) to approve or deny the grant. In this case, the grant must be explicitly approved before an outgoing payment is created.
41+
You must integrate with an [IdP](/integration/requirements/open-payments/idp) when using Rafiki's `auth` service because the Open Payments standard requires interactive outgoing payment _grant_ requests. In an interactive request, there must be explicit interaction by an individual (for example, a client's end-user) to approve or deny the grant. In this case, the grant must be explicitly approved before an outgoing payment is created.
4242

4343
:::note
4444
Rafiki’s [`frontend`](/integration/deployment/services/frontend-service) service requires an IdP for authentication and user management of your [Rafiki Admin](/admin/admin-user-guide) users. Out of the box, Rafiki uses Ory Kratos, a cloud-based user management system. Kratos is for internal use only and **cannot** be used as your customer-facing Open Payments authorization server.
4545
:::
4646

47-
For more information about interactive grants and how they work with identity providers, review the [Identity Provider](/integration/requirements/idp) page and the <LinkOut href="https://openpayments.dev/introduction/grants/">Grant negotiation and authorization</LinkOut> page in the Open Payments docs.
47+
For more information about interactive grants and how they work with identity providers, review the [Identity Provider](/integration/requirements/open-payments/idp) page and the <LinkOut href="https://openpayments.dev/introduction/grants/">Grant negotiation and authorization</LinkOut> page in the Open Payments docs.
4848

4949
## GraphQL Auth Admin API
5050

‎packages/documentation/src/content/docs/integration/requirements/open-payments/grants-revoking.mdx‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
title: Viewing and revoking grants
3+
---
4+
5+
import { Badge, Tabs, TabItem } from '@astrojs/starlight/components'
6+
import { Mermaid, CodeBlock, LinkOut } from '@interledger/docs-design-system'
7+
8+
Grants are the mechanism in Open Payments by which your account holders give permission to a client application to access their accounts and send payments on their behalf. Providing your account holders the ability to view and revoke grants is not required to implement and operate Rafiki, but allowing them to do so is critical to providing an optimal user experience.
9+
10+
## View grants
11+
12+
Use the `Grants` GraphQL query to look up all grants associated with a wallet address.
13+
14+
<Tabs>
15+
<TabItem label='Operation'>
16+
```graphql
17+
query Grants(
18+
$after: String
19+
$before: String
20+
$first: Int
21+
$last: Int
22+
$filter: GrantFilter
23+
) {
24+
grants(
25+
after: $after
26+
before: $before
27+
first: $first
28+
last: $last
29+
filter: $filter
30+
) {
31+
edges {
32+
cursor
33+
node {
34+
id
35+
client
36+
createdAt
37+
state
38+
access {
39+
createdAt
40+
id
41+
identifier
42+
limits {
43+
interval
44+
receiveAmount {
45+
assetScale
46+
value
47+
assetCode
48+
}
49+
receiver
50+
debitAmount {
51+
assetCode
52+
assetScale
53+
value
54+
}
55+
}
56+
actions
57+
type
58+
}
59+
}
60+
}
61+
pageInfo {
62+
endCursor
63+
hasNextPage
64+
hasPreviousPage
65+
startCursor
66+
}
67+
}
68+
}
69+
```
70+
</TabItem>
71+
72+
<TabItem label='Arguments'>
73+
```json
74+
{
75+
"input": {
76+
"after": null,
77+
"before": null,
78+
"first": null,
79+
"last": null,
80+
"filter": {
81+
"state": {
82+
"in": ["PROCESSING", "PENDING", "APPROVED", "FINALIZED"]
83+
},
84+
"identifier": {
85+
"in": ["https://cloud-nine-wallet-backend/accounts/gfranklin"]
86+
}
87+
}
88+
}
89+
}
90+
```
91+
</TabItem>
92+
93+
<TabItem label='Response'>
94+
```json
95+
{
96+
"data": {
97+
"grants": {
98+
"edges": [
99+
{
100+
"cursor": "82637448-30d2-4242-9c85-464821dfbaf5",
101+
"node": {
102+
"id": "82637448-30d2-4242-9c85-464821dfbaf5",
103+
"client": "https://happy-life-bank-backend/accounts/pfry",
104+
"createdAt": "2025-03-27T13:48:23.615Z",
105+
"state": "APPROVED",
106+
"access": [
107+
{
108+
"createdAt": "2025-03-27T13:48:23.617Z",
109+
"id": "05a5413b-7009-4ce1-949a-e0ff1b243268",
110+
"identifier": "https://cloud-nine-wallet-backend/accounts/gfranklin",
111+
"limits": {
112+
"interval": null,
113+
"receiveAmount": {
114+
"assetScale": 2,
115+
"value": "100",
116+
"assetCode": "USD"
117+
},
118+
"receiver": null,
119+
"debitAmount": {
120+
"assetCode": "USD",
121+
"assetScale": 2,
122+
"value": "205"
123+
}
124+
},
125+
"actions": [
126+
"create",
127+
"read",
128+
"list"
129+
],
130+
"type": "outgoing-payment"
131+
}
132+
]
133+
}
134+
}
135+
],
136+
"pageInfo": {
137+
"endCursor": "82637448-30d2-4242-9c85-464821dfbaf5",
138+
"hasNextPage": false,
139+
"hasPreviousPage": false,
140+
"startCursor": "82637448-30d2-4242-9c85-464821dfbaf5"
141+
}
142+
}
143+
}
144+
}
145+
```
146+
</TabItem>
147+
</Tabs>
148+
149+
## Revoke a grant
150+
151+
Use the `revokeGrant` GraphQL mutation to revoke a particular grant.
152+
153+
<Tabs>
154+
<TabItem label='Operation'>
155+
```graphql
156+
mutation revokeGrant($input: RevokeGrantInput!) {
157+
revokeGrant(input: $input) {
158+
id
159+
}
160+
}
161+
```
162+
</TabItem>
163+
164+
<TabItem label='Arguments'>
165+
```json
166+
{
167+
"input": {
168+
"grantId": "2117891e-4b89-42ae-984e-e0762d5888c1"
169+
}
170+
}
171+
```
172+
</TabItem>
173+
174+
<TabItem label='Response'>
175+
```json
176+
{
177+
"data": {
178+
"revokeGrant": {
179+
"id": "2117891e-4b89-42ae-984e-e0762d5888c1"
180+
}
181+
}
182+
}
183+
```
184+
</TabItem>
185+
</Tabs>

‎packages/documentation/src/content/docs/integration/requirements/idp.mdx‎ renamed to ‎packages/documentation/src/content/docs/integration/requirements/open-payments/idp.mdx‎

File renamed without changes.

‎packages/documentation/src/content/docs/integration/requirements/open-payments/wallet-keys.mdx‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Wallet address keys
3+
---
4+
5+
import { LinkOut } from '@interledger/docs-design-system'
6+
import { CodeBlock } from '@interledger/docs-design-system'
7+
import { Tabs, TabItem } from '@astrojs/starlight/components'
8+
9+
Creating a public-private key pair for each wallet address is not required when integrating with Rafiki.
10+
11+
You only need to create key pairs for wallet addresses if you want to allow your account holders to use/be Open Payments clients under their wallet addresses. For more information, review the Open Payments documentation about <LinkOut href="https://openpayments.dev/resources/glossary/#client">clients</LinkOut> and <LinkOut href="https://openpayments.dev/introduction/client-keys/">client keys</LinkOut>.
12+
13+
## Create a wallet address key pair
14+
15+
Use the `createWalletAddressKey` GraphQL mutation to create a key pair and associate it with a wallet address.
16+
17+
<Tabs>
18+
<TabItem label='Operation'>
19+
```graphql
20+
mutation CreateWalletAddressKey($input: CreateWalletAddressKeyInput!) {
21+
createWalletAddressKey(input: $input) {
22+
code
23+
message
24+
success
25+
walletAddressKey {
26+
id
27+
walletAddressId
28+
revoked
29+
jwk {
30+
alg
31+
crv
32+
kid
33+
kty
34+
x
35+
}
36+
createdAt
37+
}
38+
}
39+
}
40+
```
41+
</TabItem>
42+
43+
<TabItem label='Arguments'>
44+
45+
```json
46+
{
47+
"input": {
48+
"jwk": {
49+
"kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
50+
"x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8",
51+
"alg": "EdDSA",
52+
"kty": "OKP",
53+
"crv": "Ed25519"
54+
},
55+
"walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018"
56+
}
57+
}
58+
```
59+
60+
The request is a standard request to create a JSON Web Key (JWK), which is a JSON data structure that represents a cryptographic key. <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7517#section-4'>Section 4</LinkOut> of the JWK specification describes the format and associated parameters `kty`, `alg`, and `kid`. <LinkOut href='https://datatracker.ietf.org/doc/html/rfc7518#section-6'>Section 6</LinkOut> of the JSON Web Algorithms (JWA) specification describes the cryptographic algorithm for the keys and associated parameters `kty`, `crv`, and `x`.
61+
62+
Open Payments <LinkOut href="https://openpayments.dev/apis/wallet-address-server/operations/get-wallet-address-keys/">requires</LinkOut> the following values.
63+
64+
<div class="overflow-table">
65+
66+
| Parameter | Required value | Description |
67+
| --------- | -------------- | ----------------------------------------------------------------------------- |
68+
| `alg` | `EdDSA` | The algorithm used to generate the key pair |
69+
| `kty` | `OKP` | The key type identifying the cryptographic algorithm family used with the key |
70+
| `crv` | `Ed25519` | The cryptographic curve used with the key |
71+
72+
</div>
73+
74+
Additionally, the request must contain the `walletAddressId` of the wallet address that the key pair will be associated with.
75+
76+
</TabItem>
77+
78+
<TabItem label = 'Response'>
79+
80+
```json
81+
{
82+
"data": {
83+
"createWalletAddressKey": {
84+
"code": "200",
85+
"message": "Added Key To Wallet Address",
86+
"success": true,
87+
"walletAddressKey": {
88+
"id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
89+
"walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
90+
"revoked": false,
91+
"jwk": {
92+
"alg": "EdDSA",
93+
"crv": "Ed25519",
94+
"kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
95+
"kty": "OKP",
96+
"x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8"
97+
},
98+
"createdAt": "2023-03-03T09:26:41.424Z"
99+
}
100+
}
101+
}
102+
}
103+
```
104+
105+
</TabItem>
106+
</Tabs>
107+
108+
## Revoke a wallet address key
109+
110+
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.
111+
112+
<Tabs>
113+
<TabItem label = 'Operation'>
114+
115+
```graphql
116+
mutation RevokeWalletAddressKey($input: RevokeWalletAddressKeyInput!) {
117+
revokeWalletAddressKey(input: $input) {
118+
walletAddressKey {
119+
id
120+
revoked
121+
walletAddressId
122+
createdAt
123+
}
124+
}
125+
}
126+
```
127+
128+
</TabItem>
129+
130+
<TabItem label = 'Arguments'>
131+
```json
132+
{
133+
"input": {
134+
"id": "e7532552-cff9-4ffe-883e-56613d3ae611"
135+
}
136+
}
137+
```
138+
</TabItem>
139+
140+
<TabItem label = 'Response'>
141+
142+
```json
143+
{
144+
"data": {
145+
"revokeWalletAddressKey": {
146+
"walletAddressKey": {
147+
"id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
148+
"revoked": true,
149+
"walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
150+
"createdAt": "2023-03-03T09:26:41.424Z"
151+
}
152+
}
153+
}
154+
}
155+
```
156+
157+
</TabItem>
158+
</Tabs>

‎packages/documentation/src/content/docs/integration/requirements/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ An identity provider (IdP) is a system or service that stores and manages user i
5757

5858
You must integrate with an IdP if you plan to use the authorization server provided through Rafiki's auth service. The authorization server requires consent be collected via an interactive grant before an outgoing payment request is issued. The purpose of the IdP is to handle the authentication and consent required to authorize the interactive grant request.
5959

60-
[Integrate Rafiki with your IdP](/integration/requirements/idp)
60+
[Integrate Rafiki with your IdP](/integration/requirements/open-payments/idp)
6161

6262
## Integration checklist
6363

0 commit comments

Comments
 (0)