Service Account

The service account is a special type of non-human client that is granted limited access to your organization's resources.

Permissions

Organization

Permissions to your organization are granted through the automated invitation of Service Account technical user upon creation. All the technical users have the following email pattern:

email = clientId@vgs.dev

You can check all the Service Accounts linked to your organization in the User Access Control section of the VGS Dashboard > Organization settings page.

Organization Resources

Permissions to the resources of your organization are controlled by assigning the scopes to the service account.

Currently, there are the following scopes that you can assign to the service account:

Scope

Description

3ds:admin

Invoke all 3DS endpoint. (PayOpt)

access-logs:read

Allows to read tenant access logs

cards:read

Allow to read cards

cards:write

Allow to write cards

credentials:write

Allows full management of vault credentials

financial-instruments:admin

Grants access to manage all financial instruments across all accounts which were used during the payment

financial-instruments:read

Grants read access to financial instruments for specific sub-account

financial-instruments:write

Grants access to create a financial instrument during a payment (typically used with Checkout)

gateways:admin

Grants access to manage all gateways

merchants:write

Allow to write merchants

network-tokens:read

Ability to get network token status of an enrolled card

network-tokens:write

Ability to enroll cards into network tokens and perform lifecycle actions

orders:admin

Grants access to manage all orders across multiple accounts which were used during the payment

orders:read

Grants read access to orders for specific account

orders:write

Grants access to create an order during a payment

organizations:read

Allows reading basic organization details such as activation, status, name and user permissions list

preferences:write

Allows to read, create, update and delete preferences of the vault

routes:read

Allows read access to all routes

routes:write

Allows access to all routes operations

rules:admin

Grants access to manage all rules

sub-accounts:admin

Provides access to manage sub-accounts

threeds:admin

Provides access for configuration of 3ds providers

transfers:admin

Grants access to manage all transfers and reversals across all accounts which were used during the payment

transfers:read

Grants read access to transfers and reversals for specific account

transfers:write

Grants access to create a transfer during a payment (typically used with Checkout)

vaults:read

Allows reading vault details such as name and identifier

vaults:write

Allows to create vault and update vault

Service Account can be created either via VGS CLI or via Dashboard.

Currently, there is a limit of having a maximum of 50 service account clients per organization. If you need more, please contact [email protected]

Creating Service Accounts via VGS CLI

Authentication

The key difference in authentication with a service account is that you don't need to execute vgs login open the browser and input your credentials.

Instead, the authentication is happening automatically through the environment variables VGS_CLIENT_ID and VGS_CLIENT_SECRET which can be declared in the .env file:

VGS_CLIENT_ID=<SERVICE_ACCOUNT_CLIENT_ID>
VGS_CLIENT_SECRET=<SERVICE_ACCOUNT_CLIENT_SECRET>

In case of running in Docker, please check Authentication in Docker.

Create

To create a service account for your organization, you need to do the following:

Generate the service account configuration from the vgs-cli template and store it to the service_account.yaml file by executing:

vgs generate service-account -t vgs-cli > service_account.yaml

apiVersion: 1.0.0
kind: ServiceAccount
data:
  # Maximum amount of time before an access token expires, in seconds. (Defaults to
  # 5 minutes.)
  accessTokenLifespan: 300
  
  # List of vaults which service account should have access to.
  vaults:
    - tntcs7thayd
  
  # Non-unique name of the Service Account.
  name: vgs-cli
  
  # Scopes allow a Service Account to perform specific CLI commands.
  scopes:
    - name: access-logs:read
    - name: organizations:read
    - name: routes:write
    - name: vaults:write
    
    # An access token will not contain optional scopes unless the user requests them
    # explicitly.
    - name: financial-instruments:write
      optional: true
    - name: transfers:write
      optional: true
    - name: orders:write
      optional: true

If needed, change name and add/remove scopes according to your needs (check Organization Resources section) by editing service_account.yaml file.
Restrict service account access to specific vault(s) by adding their identifiers to vaults. If no vault(s) specified, service account won't have access to any vaults in the organization.
Apply the service account configuration stored in the service_account.yaml with your organization ID and execute:

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

As a result of the above-mentioned steps, you will have an output with two additional YAML fields:

clientId: ACxxxxxxx-vgs-cli-7Pvf5
clientSecret: 5f6cf436-6666-5555-4444-3975be84311e

Now, with clientId and clientSecret you can setup Authentication and test the VGS CLI.

If you do not store the clientSecret now, you will not be able to retrieve it again. Also, make sure to never store credentials in the version control system.

Name

The service account name can be a maximum of 20 characters and it's used for the generation of the clientId by using the following pattern:

clientId = 9 characters of ORGANIZATION_ID-name-5 random alphanumeric characters

Delete

This feature is available only starting from 1.6.5 version of the VGS CLI.

To delete a service account, execute the command:

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

Using Service Accounts via Dashboard

Create

To create a service account for your organization you need to go to the Service Accounts section of the VGS Dashboard > Organization settings page and click on a Create New button. Add a label name and scopes for this service account. The label field is for your use. Next, set vaults and scopes to provide access to resources. Please mind, scopes cannot be modified after creation. If vault(s) are not designated, the service account will have no access to any of the organization's vaults.

Delete

To delete a service account, click on the remove button next to the service account you would like to delete. Then, confirm the action.

View

You can check all the Service Accounts linked to your organization in the Service Accounts section of the VGS Dashboard > Organization settings page.

PreviousCommands NextTroubleshooting

Last updated 9 days ago