Authentication

1. Generate Service Account

• Each CMP Account is uniquely identified by a Tenant ID (also referred to as a vault ID or Account ID). CMP Accounts are accessed programmatically using Service Account credentials.

• You can generate a Service Account in the dashboard or create one using the VGS Command Line Interface (CLI).

Dashboard:

• Navigate to the Service Accounts section of your Dashboard: Vault > Organization > Service Accounts.

• Click on the Create New button.

• Select your Vault and add the following scopes to provide COF application access to Network Tokens and Account Updater:

Scope	Permission
cards:write	Required to create a card in VGS and to enroll or unenroll it in the VGS account updater.
cards:read	Required to retrieve card details and account updater information if the card is enrolled.
network-tokens:write	Required to enroll and delete a card in VGS network tokens.
network-tokens:read	Required to retrieve network token information if the card is enrolled.
cards:read-pci	Required to retrieve sensitive card data (PAN and CVC). Applicable to clients that are PCI-compliant.

CLI:

Execute the sample code below, which will create credentials.yaml file:

vgs generate service-account -t calm --var vault_id=<your_vault_id> credentials.yamlBash

2. Generate Access Token

To authenticate with the COF APIs, you should use the CLIENT_ID and CLIENT_SECRET generated in the previous step to create an access_token.

curl -X POST \
     -d "client_id=<CLIENT_ID>" \
     -d "client_secret=<CLIENT_SECRET>" \
     -d "grant_type=client_credentials" \    
      "https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token"Bash

The generated token can now be used with the COF APIs. Please note that this access_token is valid only for 20 minutes. After expiry, you can generate a new access token using the same process. refresh_token should not be used. Pass the created access_token as an Authorization: Bearer ${VGS_ACCESS_TOKEN} header in each API call.

3. Generate Access Credentials

To create access credentials, go to the Vault Settings > Access Credentials and press the Generate Credentials button. When Access Credentials are generated, you will be prompted to download them.

Note that access credentials’ secrets can only be viewed at the time of generation. You can download them to keep them safe.

If you lose these credentials, you can generate a new pair following the same process Read more.

Accessing and Handling CVC

Card Verification Code (CVC) is a security measure, typically a three-digit number on the back of the card (or four digits on some cards like American Express). It will be applicable for Clients that desire to perform transactions on behalf of their customers (MIT) and also use the CVC as part of transaction authorization upstream with their PSPs.

This is also applicable for VGS clients who want to use VGS Collect with CMP and use the PAN and CVC. Clients can directly integrate with the API. Clients can perform transactions using CVC, in addition to PAN.

Clients can store CVC in their account in a volatile way for a short period of time and it can be used multiple times during that period. Clients are enabled for CVC by default.

When a client is PCI-Client and the scope is added, these are the expected fields:

• PAN

• PAN Alias

• CVC

• CVC Alias

• CVC Status

When a client is not PCI-Client, these are the expected fields:

• PAN

• CVC

• CVC Status