# Authentication and Authorization

This api authenticates using the [OAuth2.0 client credentials flow](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/), which requires a client id and secret to attain an access token. You can create credentials in your VGS dashboard or via the VGS CLI, following these instructions [here](https://www.verygoodsecurity.com/docs/vgs-cli/service-account#using-service-accounts-via-dashboard). When you create the client credentials, assign one of the following scopes to the api,

* `aliases:read` - This scope will allow the client to read the the entire vault data object using the associated alias in order for this scope to work, the vault must be configured to reveal data by VGS Support.
* `aliases:write` - This scope will allow the client to create new aliases by value. If the value already has an alias in the requested alias format - it will return the current alias already created when fingerprinting is turned on, otherwise it will create a new alias.
* `aliases:delete` - This scope will allow the client to delete any alias based upon the alias. This will only delete the alias, if the underlying value has more than one alias, the value is still retained in the vault until all associated aliases are removed.

#### Vault level Authorization

When you create a new set of credentials, you can chose which vault(s) the credentials are authorized to operate upon. Absence of an assigned vault to the client credentials, even with the vault scopes assigned to the credential will result in a 401 - Unauthorized error. [Docs » Guides » Access credentials](https://www.verygoodsecurity.com/docs/settings/access-credentials)

#### Request example

```
curl 'https://auth.verygoodsecurity.com/auth/realms/vgs/protocol/openid-connect/token' \
  --request POST \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<client_id> \
  --data client_secret=<client_secret>
```


---

# 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/apis/vault-api/authentication-and-authorization.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.