> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/cmp/platform/authentication.md).
# Authentication
### 1. Generate Service Account
* A **service account** is a special type of non-human client that is granted limited access to your organization's resources.
* Permissions to the resources of your organization are controlled by assigning [scopes](/cmp/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/api-reference-v1/account-updater-scopes-v1.md) to the service account.
* Each [tenant](/cmp/platform/cmp-account.md) is uniquely identified by a Tenant ID (also referred to as a *Vault ID* or *Account ID*). Tenants 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:**
Generate a Service Account through the VGS Dashboard:
* Navigate to the Service Accounts section of your [VGS Dashboard](https://dashboard.verygoodsecurity.com/cmp)
* Click the "Create New" button.
* 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](/cmp/products-and-services/3ds.md) device fingerprinting/initialize and authentication. |
|
cert-manager:write
organization-users:read
organization-users:write
rules:admin
sub-accounts:admin
vaults:write
| Required to generate the Apple Pay [certificate](https://docs.verygoodsecurity.com/cmp/payment-credentials/apple-pay/create-card-apple-pay-wallet-decryption#setting-up-your-apple-certificates) used to decrypt Apple Pay tokens. |
**Note**: When tenants 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.
Generate a Service Account through the Vault Dashboard:
* Navigate to the Service Accounts section of your [Vault Dashboard](https://dashboard.verygoodsecurity.com): *Vault > Organization > Service Accounts.*
* Click on the "Create New" button.
* 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.
Also required for Apple Pay Decrypt.
|
| 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](/cmp/products-and-services/3ds.md) device fingerprinting/initialize and authentication. |
|
|
***
Extra Context: Accessing and Handling CVC
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
\
\
**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= credentials.yamlBash
```
### 2. Generate Access Token
To authenticate with the [CMP APIs](/cmp/developer-resources/api.md), you should use the `CLIENT_ID` and `CLIENT_SECRET` generated in the [previous step](#id-1-generate-service-account) to create an `access_token`.
Open a command-line application like Terminal and execute the sample curl request below, replacing the `CLIENT_ID` and `CLIENT_SECRET` values with those connected to your Service Account.
```bash
curl -X POST -d "client_id=" -d "client_secret=" -d "grant_type=client_credentials" "https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token"
```
The generated token can now be used with the CMP APIs.
{% hint style="info" %}
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.
{% endhint %}
### 3. Generate a test card
To create a test card, copy the access token generated in the previous step, replace the value `$VGS_ACCESS_TOKEN` , and execute the request.
{% code overflow="wrap" expandable="true" %}
```bash
curl -X POST "https://sandbox.vgsapi.com/cards" \
-H "Authorization: Bearer $VGS_ACCESS_TOKEN" \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"attributes": {
"pan": "4111111111111111",
"exp_month": 12,
"exp_year": 30,
"cvc": "123",
"cardholder": { "name": "Test Cardholder" }
},
"meta": { "source": "test10101-onboarding" }
}
}'
```
{% endcode %}
When the test card is successfully created, you can review its information in the VGS Dashboard under the *Credentials* navigation item.
### 4. Configure your Collect form
Configure a Collect form to collect sensitive information, like card data, from an "end-user" interface without it needing to pass through your systems. All Sandbox tenants are automatically created with a "default" Collect form.
For more information on how to integrate VGS Collect into your web application and create card objects through VGS Collect, see our [documentation](/cmp/developer-resources/guides/create-a-card-using-vgs-collect.md).
### 5. Generate Access Credentials
If you plan to send tokenized card data to a third party, like a Payments Service Provide (PSP), you can use [Outbound routes](/vault/http-proxy/outbound-connection.md) (also known as a forward proxy) to achieve this securely. To configure an Outbound route, you must first generate access credentials to authenticate the traffic.
To create access credentials, go to the [VGS Dashboard](https://dashboard.verygoodsecurity.com/cmp) *> Routes > Access Credentials* and press the "Generate Credentials" button. When Access Credentials are generated, you will be prompted to download them.\
\
For more information on how to integrate Routes into your payment flow, see our [documentation.](/vault/http-proxy/inbound-connection.md)
{% 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.verygoodsecurity.com/cmp/platform/authentication.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.
