# 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](https://dashboard.verygoodsecurity.com) 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 | | `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 | | `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 ## 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: ```bash VGS_CLIENT_ID= VGS_CLIENT_SECRET= ``` In case of running in Docker, please check [Authentication in Docker](https://docs.verygoodsecurity.com/vault/developer-tools/docker#authenticate-with-service-account). ### 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: ```bash vgs generate service-account -t vgs-cli > service_account.yaml ``` ```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. ``` * If needed, change **name** and add/remove scopes according to your needs (check [Organization Resources](#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: ```bash vgs apply service-account -O -f service_account.yaml ``` As a result of the above-mentioned steps, you will have an output with two additional YAML fields: ```yaml clientId: ACxxxxxxx-vgs-cli-7Pvf5 clientSecret: 5f6cf436-6666-5555-4444-3975be84311e ``` Now, with **clientId** and **clientSecret** you can setup [Authentication](#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](https://pypi.org/project/vgs-cli/1.6.5/) version of the VGS CLI. To delete a service account, execute the command: ```bash vgs delete service-account -O ``` ## 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](https://dashboard.verygoodsecurity.com) 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. !['Create Service Account'](https://2096104711-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUreALQAfVnRMQEz110rC%2Fuploads%2Fgit-blob-d067008ec8c5764410227de2454403613b5fc3e1%2Fcreate-service-account-modal.png?alt=media) ### 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](https://dashboard.verygoodsecurity.com).
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/service-account.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.