Authentication - V1

API Credentials

Payment Optimization APIs use OAuth 2.0 Client Credentials flow for authentication. This API is intended for server to server communication, and no user is involved in the process.

Generate Service Account

API credentials can be generated using Service Account on VGS CLI:

Generate the service account configuration for your vault by executing the sample below, storing it in the credentials.yaml file

vgs generate service-account -t calm --var vault_id=<VAULT_ID> > credentials.yaml

Your credentials.yaml will look like below.

apiVersion: 1.0.0
kind: ServiceAccount
data:
  clientId: <CLIENT_ID>
  clientSecret: <CLIENT_SECRET>
  name: calm
  scopes:
    - cards:write
    - cards:read

If needed, change the name and add/remove scopes according to your needs in credentials.yaml file.

Annotation vgs.io/vault-id with your vault identifier is required to authorize requests that are specific to the vault that you want to use with Payment Optimization.

Generate Credentials

Apply the service account configuration stored in the credentials.yaml with your organization ID and execute:

vgs apply service-account -O <ORGANIZATION_ID> -f credentials.yaml

As a result of the previous step, you will have an output that will look similar to:

apiVersion: 1.0.0
kind: ServiceAccount
data:
  clientId: <CLIENT_ID>
  clientSecret: <CLIENT_SECRET>
  name: calm
  scopes:
    - cards:write
    - cards:read

Output will be different depending on the template used to generate service account

Please make sure always to store these credentials in a secure environment. They should never be exposed.

Generated credentials can be located on VGS Dashboard under the Organization Settings page:

Please note that Write organization access is required for credentials to work (set by default).

How To Authenticate

VGS API authentication server is available at https://auth.verygoodsecurity.com.

The first thing you'd need to authenticate is API credentials from the previous step: CLIENT_ID and CLIENT_SECRET.

With these two pieces of information in hand, you’re ready to authenticate. Here is an example request for obtaining an access token and its response:

Request

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"

Response

{
 "access_token":"...",
 "expires_in":300,
 "refresh_expires_in":0,
 "token_type": "bearer",
 "not-before-policy": 1620379100,
 "scope": "cards:write user_id service-account",
}

Now you're ready to call an API with the obtained access_token. Generated token can be used with VGS Account Updater API only within the specified vault with the vgs.io/vault-id annotation. Please note that access_token is valid only for 5 minutes. After that, you need to obtain a new access token using the same request. refresh_token should not be used.

The obtained access_token value should be passed in Authorization: Bearer ${VGS_ACCESS_TOKEN} header in each API call.

For simple usage of cURL commands across our documentation, you can store the access_token in an environment variable (requires jq):

VGS_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' | jq -r .access_token`

How To Revoke Credentials

In case you need to revoke access to payment optimization services for particular credentials, you can follow these steps:

1

Using VGS CLI (preferred)

vgs delete service-account <CLIENT_ID> -O <ORGANIZATION_ID>

2

Via VGS Dashboard

Remove the user named <CLIENT_ID>@vgs.dev from the VGS Dashboard under the Organization Settings page.