Authentication - V1

API Credentials

The VGS Network Tokenization 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 authentication process. The steps to set this up with VGS are detailed below.

1

Generate a Service Account

API credentials can be generated using a Service Account with the VGS CLI.

The service account configuration can be generated for your vault by executing the sample code below, which will create a credentials.yaml file:

Generate service account

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

Your credentials.yaml file will contain the following code:

apiVersion: 1.0.0
  kind: ServiceAccount
  data:
    annotations:
      "vgs.io/vault-id": "<VAULT_ID>"
    name: calm
    scopes:
      - name: cards:write
      - name: network-tokens:write

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

Do not remove the vgs.io/vault-id annotation field. Requests are authorized per-vault; you may modify this field to contain the Vault ID that you want to use with Network Tokens.

2

Generate Credentials

Apply the service account configuration stored in the credentials.yaml file with your organization ID by executing the following code:

Apply service account

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

After executing, you should receive the following output, containing your credentials:

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

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

Generated credentials can be located on the 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

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

To authenticate with the VGS Network Tokens API, use the CLIENT_ID and CLIENT_SECRET generated in the previous step to create a Bearer access token.

Example cURL request for obtaining an access token:

Obtain 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"

Example response:

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

The generated token can be used with the Network Token APIs only within the vault specified in the vgs.io/vault-id annotation field. The access_token is valid for 5 minutes. After that, obtain a new access token using the same process. refresh_token should not be used.

Pass the created access_token in the Authorization: Bearer ${VGS_ACCESS_TOKEN} header in each API call.

How To Revoke Credentials

In case you need to revoke access to payment optimization services for particular credentials, there are two ways to do this:

• Using the VGS CLI (preferred):

Revoke with VGS CLI

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

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

Scopes

OAuth 2.0 scopes allow you to specify the level of API access required. Since API credentials are limited per vault, API scopes are limited only for that vault as well. Once an access token is granted via authentication flow, scopes can be located in the issued JWT.

Network Token API credentials can have the following scopes:

Scope	Permission
cards:write	Enroll and manage a card in VGS Network Tokens
cards:read	Read details about the enrolled card
network-tokens:write	Enroll and manage a VGS network token
network-tokens:read	Read details about the enrolled network tokens

What's next?

• Enroll a Network Token

• API docs