Advanced authentication for Vault Forward

When using Vault Forward, the authentication to the downstream API is done by passing in the authorization header, you will need to pass your own API keys and credentials through the body or headers. For example, when using a bearer token, it needs to be passed in the Vault Forward request as a x-vault-forward-header-authorization header.

POST /vault-forward
host: api.acme.gr4vy.app
content-type: application/json
x-vault-forward-url: https://example.com/endpoint
x-vault-forward-http-method: PUT
x-vault-forward-header-authorization: Bearer 123
...

In some situations, passing through the authentication is not technically possible.

• The downstream service requires the request to be signed
• The downstream service requires two-way SSL / mutual TLS authentication
• The downstream service requires the entire payload to be encrypted

For these services, we have added support for advanced authentication.

​

Setup

To set up advanced authentication, head over to the dashboard, switch to Settings -> Merchants then edit a merchant using the actions menu, … -> Edit merchant. In a single merchant environment you may be able to go to this screen directly via the Settings -> Configuration menu.

Next, switch to the Vault Forwarding tab and you should see the endpoints enabled for your environment.

When an endpoints supports authentication, e.g. Visa, the actions menu should have an option to edit the Authentication methods. Click on this menu, and it will take you to a new screen to set up an authentication.

To set up an authentication method, click on the Add authentication, and select the method to add for that endpoint. Fill in any of the required fields, and finally click the Add button.

Once set up, please note the UUID of each authentication method as you will need it in the next step.

​

Usage

To can make a Vault Forward request with an authentication method use the x-vault-forward-authentications header with a list of one or more authentication methods UUIDs (comma separated) to use on that request. Each authentication method has it’s unique UUID that is displayed in the dashboard.

POST /vault-forward
host: api.acme.gr4vy.app
content-type: application/json
x-vault-forward-url: https://example.com/endpoint
x-vault-forward-http-method: PUT
x-vault-forward-payment-methods: b77fef6d-c360-4b42-8f70-d884f4a6852a
x-valud-forward-authentications: 0a71cd3f-021e-4528-bcd7-38772594634b,2168f3c2-e327-47bd-9d5a-e9cfaeb53e96

{
    "cards": [
        {
            "number": "{{ CARD_NUMBER_1 }}",
            "expiry": "{{ CARD_EXPIRATION_DATE_1 }}",
            "cvv": "123"
        }
    ]
}

We will apply each authentication method to a request before we send it on to the target endpoint.