VGS Show

VGS Show is a way to reveal information from VGS to the final user without revealing the information to the backend, even when the external service doesn't return the information again.

Sometimes, the external service does not return the information that the final users needs, and because of that you cannot reveal that information to the final user. In these cases, you have to use the Linker Show endpoint.

You can find the endpoint in src/vault, but before that, you will need to configure some VGS rules to make it work.

When to use the Linker Show endpoint

You will only need to use this endpoint if you meet these 3 points:

• You send the information to the external service but the external service doesn't return this information again. (Example: You send the SSN to create a customer but the external service doesn't return the full SSN again).

• You want to show this information in the app. (Example: There is a screen in the frontend where you want to show the full SSN).

• You don't want to save that raw information in your database (Example: The SSN).

How it works

Frontend sends the information to the external service flow

Linker application sends the information

1. The Linker app sends the information required for the endpoint.

2. VGS tokenizes the information specified by the rules and returns it to Linker API.

3. Linker API saves the token into the database.

Return the information to the frontend flow

Linker returns the token

1. The app requests which token wants to reveal by sending the "type".

2. Linker API searches the token by the type in the database and returns it.

3. VGS intercepts that requests and replaces the token with the real information.

How to create a new VGS Rule for the Linker Show endpoint

To understand this VGS rule, you must have an understanding between inbound vs outbound routes, volatile vs persistent storages, on request vs on response phases and redact vs reveal operations.

If you want to create a new rule that will use the Show endpoint, you will have to do the following:

1. Create the inbound rule to tokenize the information you want in the endpoint where the app sends that information.

Inbound rule tokenizing the SSN

In this example, we are tokenizing the SSN with a BaaS service in the /baas/customer-enrollment endpoint.

This is it, because we only have the SSN the first time the user sends it, but the BaaS doesn't return the SSN back at any time.

So if we want to show the SSN to the user at any other time, without saving that raw information in our database, we have to use the Show endpoint.

And because the token will be only available to us when the frontend sends the SSN in this endpoint, we have to make the storage persistent.

1. In the Linker API, you will have to:

• Save the token into the database in the endpoint you have mapped in the rule. In this case, we have mapped that the token will be the ssn in the body request, so we can take the ssn from the body in our endpoint and save it in the table that makes most sense. In this example, the ssn tokenized will be save into the User table.

• Create a type in the src/vault/enums/token-type.enum.ts file.

src/vault/enums/token-type.enum.ts

export enum TokenType {
  SSN = 'ssn',
}

This will let the Linker app send a request to the Show endpoint with this new type.

• Create the logic to get the token in the Show endpoint in src/vault/vault.service.ts.

src/vault/vault.service.ts

switch (showDto.type) {
  case TokenType.SSN:
    token = user.ssn;
    break;
}

In this case, we are setting the token variable to the tokenized ssn we have saved previously.

• Make sure that you have the Show rule in your inbound rules.

This rule will be given to you in the YAML file of the inbound route.

What this rule does is take the response from Linker Show endpoint and send the raw information to the linker app depending on the token we have returned.