# Authentication - V1

## API Credentials

The VGS Network Tokenization APIs use [OAuth 2.0 Client Credentials flow](https://oauth.net/2/grant-types/client-credentials/) 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.

{% stepper %}
{% step %}

### Generate a Service Account

API credentials can be generated using a [Service Account](/cmp/platform/authentication.md#id-1-generate-service-account) with the [VGS CLI](/cmp/platform/authentication.md#id-1-generate-service-account).

The service account configuration can be generated for your vault by executing the sample code below, which will create a **credentials.yaml** file:

{% code title="Generate service account" %}

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

{% endcode %}

Your **credentials.yaml** file will contain the following code:

```yaml
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](/cmp/platform/authentication.md#id-1-generate-service-account) according to your needs in the `credentials.yaml` file.

{% hint style="warning" %}
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.
{% endhint %}
{% endstep %}

{% step %}

### Generate Credentials

Apply the service account configuration stored in the **credentials.yaml** file with your organization ID by executing the following code:

{% code title="Apply service account" %}

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

{% endcode %}

After executing, you should receive the following output, containing your credentials:

```yaml
apiVersion: 1.0.0
  kind: ServiceAccount
  data:
    clientId: <CLIENT_ID>
    clientSecret: <CLIENT_SECRET>
    name: calm
    scopes:
      - name: cards:write
      - name: network-tokens:write
```

{% hint style="warning" %}
Please make sure always to store these credentials in a secure environment. They should never be exposed.
{% endhint %}

Generated credentials can be located on the [VGS Dashboard](https://dashboard.verygoodsecurity.com) under the Organization Settings page:

Please note that `Write` organization access is required for credentials to work (set by default).
{% endstep %}
{% endstepper %}

## How To Authenticate

The VGS API authentication server is available at [https://auth.verygoodsecurity.com](https://auth.verygoodsecurity.com/).

To authenticate with the VGS Network Tokens API, use the `CLIENT_ID` and `CLIENT_SECRET` generated in the previous step to create a `Bearer` access token.

Example cURL request for obtaining an access token:

{% code title="Obtain 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"
```

{% endcode %}

Example response:

```json
{
 "access_token":"...",
 "expires_in":300,
 "refresh_expires_in":0,
 "token_type": "bearer",
 "not-before-policy":1620379100,
 "scope": "cards:write user_id service-account",
}
```

{% hint style="info" %}
The generated token can be used with the Network Token APIs only within the vault specified in the **vgs.io/vault-id** annotation field. The `access_token` is valid for 5 minutes. After that, obtain a new access token using the same process. `refresh_token` should not be used.
{% endhint %}

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):

{% code title="Revoke with VGS CLI" %}

```bash
vgs delete service-account <CLIENT_ID> -O <ORGANIZATION_ID>
```

{% endcode %}

* 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](https://oauth.net/2/scope/) 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](/cmp/platform/authentication.md#id-2-generate-access-token), scopes can be located in the issued JWT.

[Network Token API credentials](/cmp/developer-resources/api/credential-management-v1-apis-calm/network-tokens-v1/network-tokens-api-v1.md) 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](/cmp/developer-resources/api/credential-management-v1-apis-calm/network-tokens-v1/network-tokens-api-v1/network-tokens-bulk-enrollment-v1.md)
* [API docs](/cmp/developer-resources/api/credential-management-v1-apis-calm/network-tokens-v1/network-tokens-api-v1.md)


---

# 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/cmp/developer-resources/api/credential-management-v1-apis-calm/network-tokens-v1/network-tokens-api-v1/authentication-v1.md?ask=<question>
```

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.