# Authentication

### 1. Generate Service Account <a href="#id-1-generate-service-account" id="id-1-generate-service-account"></a>

* A **service account** is a special type of non-human client that is granted limited access to your organization's resources.&#x20;
  * Permissions to the resources of your organization are controlled by assigning [scopes](https://docs.verygoodsecurity.com/cmp/developer-resources/api/card-management-v1-apis-calm/account-updater-v1/api-reference-v1/account-updater-scopes-v1) to the service account.
* Each [CMP Account](https://docs.verygoodsecurity.com/cmp/platform/cmp-account) is uniquely identified by a Tenant ID (also referred to as a *Vault ID* or *Account ID*). CMP Accounts are accessed programmatically using Service Account credentials.
* You can generate a Service Account in the dashboard or create one using the VGS Command Line Interface (CLI)

\
**Generate a Service Account through UI:**

<details>

<summary><strong>Generate a Service Account through the CMP Dashboard:</strong></summary>

* Navigate to the Developer Tools section of your [CMP Dashboard](https://dashboard.verygoodsecurity.com/cmp) and select the 'Service accounts' tab
* Click the "Create New" button.

<figure><img src="https://236204706-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg1pA9re6lCmtaiQAnvjh%2Fuploads%2Ft0zGTQ9yQoxInmHRjbx5%2FScreenshot%202025-12-16%20at%203.11.48%E2%80%AFPM.png?alt=media&#x26;token=d8875676-4176-4dde-8d39-488f3724f731" alt=""><figcaption></figcaption></figure>

* Add the following scopes to provide CMP application access to Network Tokens and Account Updater:

| Scope                | Permission                                                                                                                                                 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cards:write          | Required to create a card in VGS and to enroll or unenroll it in the VGS account updater.                                                                  |
| cards:read           | Required to retrieve card details and account updater information if the card is enrolled.                                                                 |
| network-tokens:write | Required to enroll and delete a card in VGS network tokens.                                                                                                |
| network-tokens:read  | Required to retrieve network token information if the card is enrolled.                                                                                    |
| cards:read-pci       | Required to retrieve sensitive card data (PAN and [CVC](#heading-title-text)). Applicable to clients that are PCI-compliant.                               |
| 3ds:write            | Required to initiate or manage [3DS](https://docs.verygoodsecurity.com/cmp/products-and-services/3ds) device fingerprinting/initialize and authentication. |

**Note**: When CMP accounts are configured, they are configured with an existing account-tenant relationship. This means that service accounts created for a CMP account do not require the extra step to target a specific tenant/vault.

</details>

<details>

<summary><strong>Generate a Service Account through the VGS Vault Dashboard:</strong></summary>

* Navigate to the Service Accounts section of your [Vault Dashboard](https://dashboard.verygoodsecurity.com): *Vault > Organization > Service Accounts.*
* Click on the "Create New" button.

<figure><img src="https://236204706-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg1pA9re6lCmtaiQAnvjh%2Fuploads%2FUrgokJvYSLVwKSHl2RVv%2FScreenshot%202025-10-02%20at%204.02.43%E2%80%AFPM.png?alt=media&#x26;token=ae1c6673-2a6e-47fc-87b9-48fb9436bfab" alt=""><figcaption></figcaption></figure>

* Select your desired Tenant/Vault and add the following scopes to provide CMP application access to Network Tokens and Account Updater:

| Scope                | Permission                                                                                                                                                 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cards:write          | Required to create a card in VGS and to enroll or unenroll it in the VGS account updater.                                                                  |
| cards:read           | Required to retrieve card details and account updater information if the card is enrolled.                                                                 |
| network-tokens:write | Required to enroll and delete a card in VGS network tokens.                                                                                                |
| network-tokens:read  | Required to retrieve network token information if the card is enrolled.                                                                                    |
| cards:read-pci       | Required to retrieve sensitive card data (PAN and [CVC](#heading-title-text)). Applicable to clients that are PCI-compliant.                               |
| 3ds:write            | Required to initiate or manage [3DS](https://docs.verygoodsecurity.com/cmp/products-and-services/3ds) device fingerprinting/initialize and authentication. |

</details>

***

<details>

<summary>Extra Context: Accessing and Handling CVC</summary>

Card Verification Code (CVC) is a security measure, typically a three-digit number on the back of the card (or four digits on some cards like American Express). It will be applicable for Clients that desire to perform transactions on behalf of their customers (MIT) and also use the CVC as part of transaction authorization upstream with their PSPs.

This is also applicable for VGS clients who want to use VGS Collect with CMP and use the PAN and CVC. Clients can directly integrate with the API. Clients can perform transactions using CVC, in addition to PAN.

Clients can store CVC in their account in a volatile way for a short period of time and it can be used multiple times during that period. Clients are enabled for CVC by default.

When a client is PCI-Client and the `cards:read-pci` scope is added, these are the expected fields:

* PAN
* PAN Alias
* CVC
* CVC Alias
* CVC Status

When a client is not PCI-Client and the `cards:read-pci` is *not* added, these are the expected fields:

* PAN
* CVC
* CVC Status

</details>

\
\
**Generate a Service Account through CLI:**

Execute the sample code below, which will create `credentials.yaml` file:

```bash
vgs generate service-account -t calm --var vault_id=<your_vault_id> credentials.yamlBash
```

### 2. Generate Access Token <a href="#id-2-generate-access-token" id="id-2-generate-access-token"></a>

To authenticate with the [CMP APIs](https://docs.verygoodsecurity.com/cmp/developer-resources/api), you should use the CLIENT\_ID and CLIENT\_SECRET generated in the [previous step](#id-1-generate-service-account) to create an `access_token`.

```bash
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"Bash
```

The generated token can now be used with the CMP APIs. Please note that this `access_token` is valid only for 20 minutes. After expiry, you can generate a new access token using the same process. `refresh_token` should not be used. Pass the created `access_token` as an Authorization: `Bearer ${VGS_ACCESS_TOKEN}` header in each API call.

### 3. Generate Access Credentials <a href="#id-3-generate-access-credentials" id="id-3-generate-access-credentials"></a>

To create access credentials, go to the [Vault Dashboard](https://dashboard.verygoodsecurity.com/) *> Vault > Vault Settings > Access Credentials* and press the "Generate Credentials" button. When Access Credentials are generated, you will be prompted to download them.

<figure><img src="https://236204706-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg1pA9re6lCmtaiQAnvjh%2Fuploads%2F1I0TtthLMEpwjQnKd0i4%2FScreenshot%202025-10-02%20at%204.04.31%E2%80%AFPM.png?alt=media&#x26;token=7f0acccd-419a-4318-bb2b-bf0723fbdbfd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Note that access credentials’ secrets can only be viewed at the time of generation. You can download them to keep them safe.
{% endhint %}

If you lose these credentials, you can generate a new pair following the same process.

<br>