> 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/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/api-reference-v1/authentication-v1.md). # Authentication - V1 ## API Credentials Payment Optimization 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 process. ### Generate Service Account API credentials can be generated using [Service Account](/cmp/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/api-reference-v1/authentication-v1.md#generate-service-account) on VGS CLI: Generate the service account configuration for your vault by executing the sample below, storing it in the **credentials.yaml** file ```bash vgs generate service-account -t calm --var vault_id= > credentials.yaml ``` Your **credentials.yaml** will look like below. ```yaml apiVersion: 1.0.0 kind: ServiceAccount data: clientId: clientSecret: name: calm scopes: - cards:write - cards:read ``` If needed, change the **name** and add/remove scopes according to your needs in `credentials.yaml` file. > Annotation **vgs.io/vault-id** with your vault identifier is required to authorize requests that are specific to the vault that you want to use with Payment Optimization. ### Generate Credentials Apply the service account configuration stored in the **credentials.yaml** with your organization ID and execute: ```bash vgs apply service-account -O -f credentials.yaml ``` As a result of the previous step, you will have an output that will look similar to: ```yaml apiVersion: 1.0.0 kind: ServiceAccount data: clientId: clientSecret: name: calm scopes: - cards:write - cards:read ``` > Output will be different depending on the template used to generate service account > Please make sure always to store these credentials in a secure environment. They should never be exposed. Generated credentials can be located on VGS Dashboard under the Organization Settings page: Please note that `Write` organization access is required for credentials to work (set by default). ## How To Authenticate VGS API authentication server is available at [https://auth.verygoodsecurity.com](https://auth.verygoodsecurity.com/). The first thing you'd need to authenticate is API credentials from the previous step: `CLIENT_ID` and `CLIENT_SECRET`. With these two pieces of information in hand, you’re ready to authenticate. Here is an example request for obtaining an access token and its response: {% tabs %} {% tab title="Request" %} ```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" ``` {% endtab %} {% tab title="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", } ``` {% endtab %} {% endtabs %} Now you're ready to call an API with the obtained `access_token`. Generated token can be used with VGS Account Updater API **only** within the specified vault with the **vgs.io/vault-id** annotation. Please note that `access_token` is valid only for 5 minutes. After that, you need to obtain a new access token using the same request. `refresh_token` should not be used. The obtained `access_token` value should be passed in `Authorization: Bearer ${VGS_ACCESS_TOKEN}` header in each API call. {% hint style="info" %} For simple usage of cURL commands across our documentation, you can store the `access_token` in an environment variable (requires [jq](https://github.com/stedolan/jq)): ```bash VGS_ACCESS_TOKEN=`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' | jq -r .access_token` ``` {% endhint %} ## How To Revoke Credentials In case you need to revoke access to payment optimization services for particular credentials, you can follow these steps: {% stepper %} {% step %} ### Using VGS CLI (preferred) ```bash vgs delete service-account -O ``` {% endstep %} {% step %} ### Via VGS Dashboard Remove the user named `@vgs.dev` from the VGS Dashboard under the Organization Settings page. {% endstep %} {% endstepper %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/credential-management-v1-apis-calm/account-updater-v1/api-reference-v1/authentication-v1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.