> 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/vault/developer-tools/apis/vault-api/authentication-and-authorization.md).

# 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
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/vault/developer-tools/apis/vault-api/authentication-and-authorization.md?ask=<question>&goal=<endgoal>
```

`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.