Authentication

Authentication

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:

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:

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

After executing, you should receiving 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, you should use the CLIENT_ID and CLIENT_SECRET generated in the previous step to create an Bearer access token.

Here is an example cURL request for obtaining an access token and its response:

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"

{
 "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 now be used with the Network Token APIs, only within the vault specified in the vgs.io/vault-id annotation field. Please note that the access_token is valid for only 5 minutes. After that, you need to 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):

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