Authentication and Authorization

This api authenticates using the OAuth2.0 client credentials flow, 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. 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

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>