Wallet address keys

Creating a public-private key pair for each wallet address isn’t required when integrating with Rafiki.

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 clients and client keys.

Directed identity

Instead of registering a wallet address key pair, a client can pass a JSON Web Key (JWK) directly in the grant request. This is known as directed identity. It removes the need for the authorization server to fetch keys from a wallet address JSON Web Key Set (JWKS) endpoint. This is useful for clients that don’t have a wallet address, or don’t want to disclose one.

Directed identity is only available for non-interactive grants (incoming payments and quotes). If INCOMING_PAYMENT_INTERACTION or QUOTE_INTERACTION is set to true, directed identity can’t be used for that grant type.

When a grant uses directed identity, its client field is null in the Auth Admin API. See Viewing and revoking grants for how this affects grant queries.

Create a wallet address key pair

Use the createWalletAddressKey GraphQL mutation to create a key pair and associate it with a wallet address.

Operation

mutation CreateWalletAddressKey($input: CreateWalletAddressKeyInput!) {
  createWalletAddressKey(input: $input) {
    walletAddressKey {
      id
      walletAddressId
      revoked
      jwk {
        alg
        crv
        kid
        kty
        x
      }
      createdAt
    }
  }
}

Variables

{
  "input": {
    "jwk": {
      "kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
      "x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8",
      "alg": "EdDSA",
      "kty": "OKP",
      "crv": "Ed25519"
    },
    "walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018"
  }
}

The request is a standard request to create a JSON Web Key (JWK), which is a JSON data structure that represents a cryptographic key. Section 4 of the JWK specification describes the format and associated parameters kty, alg, and kid. Section 6 of the JSON Web Algorithms (JWA) specification describes the cryptographic algorithm for the keys and associated parameters kty, crv, and x.

Open Payments requires the following values.

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

Additionally, the request must contain the walletAddressId of the wallet address that the key pair will be associated with.

Response

{
  "data": {
    "createWalletAddressKey": {
      "walletAddressKey": {
        "id": "f2953571-f10c-44eb-ab41-4450a7ad6771",
        "walletAddressId": "695e7546-1803-4b45-96b6-6a53f4082018",
        "revoked": false,
        "jwk": {
          "alg": "EdDSA",
          "crv": "Ed25519",
          "kid": "keyid-97a3a431-8ee1-48fc-ac85-70e2f5eba8e5",
          "kty": "OKP",
          "x": "ubqoInifJ5sssIPPnQR1gVPfmoZnJtPhTkyMXNoJF_8"
        },
        "createdAt": "2023-03-03T09:26:41.424Z"
      }
    }
  }
}

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.

Operation

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

Variables

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

Response

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