Links

Server-to-server consent

As stated before, many operations, such as initiating a payment, are sensitive and would normally require a user consent. This is obtained by sending a text message to the user. The user then consents via the web browser, following the procedure previously described. All these operations have to be performed by the users themselves. It can get extremely tedious if thousands of operations are awaiting a consent, conducted by a human.
This is where server-to-server consent comes into play. More precisely, it avoids the intervention of a human being in all interactions and opens up new opportunities: generation of single use virtual cards to pay merchants, batch payments, send refund transfers, etc...
Please note that for security & regulatory reasons, server-to-server consent is bound to the legal representative's project account (i.e no consents with key from project 1 on project 2). More specifically, this feature is ONLY accepted for operations performed on the partner's account. It cannot be implemented in your final customers' accounts.

How does it work?

This feature relies on key cryptography. This model involves a pair of keys, public and private. These are both associated with an entity (legal representative, in our case). Every public key is stored in the project settings, and its corresponding private key has to be kept secret on the partner's side.
The public key, as well as a list of trusted IP addresses, are saved in your dashboard.

Security specifications

Any operation required for the setup of the feature (public key and IP adresses setup) must be performed with 2FA consent. Additionally, any operation required for modification of the configurations (such as public key renewal) must also be performed with 2FA consent. This consent will have to be performed by the project legal representative.
You must provide a public key that will be used to verify the server signature.
Cryptographic key has to follow these specifications, in order to enhance its security level and comply with Swans' security requirements:
  • Key algorithm to be used:
    • ECDSA with reputed strong curve (such as p-256)
    • Key type must be exported in JWK
  • Swan strongly advises the partner to renew the key pair every 730 days the latest
As of today, any key not respecting the above requirements will not be accepted.

Generating your keys

Below is a simple example using your browser crypto API.
await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"])
.then(async ({ publicKey, privateKey }) => ({
publicKey: await crypto.subtle.exportKey("jwk", publicKey),
privateKey: await crypto.subtle.exportKey("jwk", privateKey),
}))
.then(keys => ({
publicKey: JSON.stringify(keys.publicKey),
privateKey: JSON.stringify(keys.privateKey),
}));
You should obtain a pair of keys like the following:
{
'{"crv":"P-256","d":"{{dVALUE}}","ext":true,"key_ops":["sign"],"kty":"EC","x":"{{xVALUE}}","y":"{{yVALUE}}"}'
'{"crv":"P-256","ext":true,"key_ops":["verify"],"kty":"EC","x":"{{xVALUE}}","y":"{{{yVALUE}}}"}'
}
You can use the above keys to:
  • install the public key in your server consent settings, and
  • the private key to sign your consent challenges
Generating your pair of keys using these cryptographic standards can be done using various libraries or packages.
As an example, https://git.}.com/coolaj86/eckles-cli.js or https://git.coolaj86.com/coolaj86/rasha.js provide similar mechanisms to generate your pair of keys using the right methods in the flavour of your choice.

Public key installation

To use server-to-server consent, you must:
  1. 1.
    connect to your dashboard
  2. 2.
    access the Developers tab where you will find the Server Consent menu entry
  3. 3.
    From there, if you are in Sandbox, installation is straightforward
    1. 1.
      Simply copy and paste your Public key
    2. 2.
      Add one or more IPs to whitelist
  4. 4.
    You're ready!
In order to save your Server-to-Server Consent configuration on your live environment, a consent is sent to the project Legal Representative.
This consent notification will contain:
  • your first & last name : "who's requesting the installation of the key"
  • the key : "what's requested to be reviewed and installed"

Signing consents using your private key

You now have a private key (installed on your server) and a public key (installed in your Swan Dashboard).
To use the GrantConsentWithServerSignature mutation described below, you must use a project access token.
To sign your first server-to-server consent, you must:
{
"data": {
"consents": {
"edges": [
{
"node": {
"id": "{{CONSENT_ID}}",
"challenge": "{{CONSENT_CHALLENGE}}",
"purpose": "AddCard",
"status": "Created"
}
}
]
}
}
}
  • You must now sign the challenge field using your private key
You can sign the challenge using the following script
Signing the consent challenge
1
await signAndExportJwtToken("{{PRIVATE_KEY_JWK}}", {
2
header: { alg: "ES256", typ: "JWT" },
3
payload: { challenge: "{{CONSENT_CHALLENGE}}" },
4
});
5
Request
Response
mutation MyMutation {
GrantConsentWithServerSignature {
consentId: "{{CONSENT_ID}}" ,
signature: "{{SIGNED_CONSENT_CHALLENGE}}",
}
) {
... on CreateMultiConsentSuccessPayload {
__typename
consent {
consentUrl
}
}
}
}
{
"data": {
"grantConsentWithServerSignature": {
"__typename": "GrantConsentWithServerSignatureSuccessPayload",
"consent": {
"id": "{{CONSENT_ID}},
"status": "Accepted"
}
}
}
}
Consent workflow with server consent
Not all of Swan's mutations can be used with grantConsentWithServerSignature mutation.
Any mutation not listed below will throw a rejection if a server consent is attempted.

Revoking your public key

Once the public key is installed, Swan provides a fast and easy way to revoke it.
This revoking mechanism will instantly remove your public key from your project, and any new consent signed will be rejected.
Please note that you will not be able to reuse this public key in the future for your live project.
You must make sure that:
  • all operations and consents to be granted are paused before you install your new public key and restart calling GrantConsentWithServerSignature
  • You have a new pair of keys ready to be installed on your systems and project.