User Accounts API

Overview

The VGS User Accounts API provides a secure, self-service way for you to retrieve detailed information about your users and their assigned roles. You can use this API to access real-time account and permission data at both the organization level and the vault level. This helps you easily manage user access, support internal audits, and maintain compliance.

VGS Roles & Permissions

Below is an overview of the roles and associated permissions referenced in the API payloads:

• Organization Roles: See the full breakdown of existing organization roles here.

• Vault Roles: See the full breakdown of existing vault roles here.

API Documentation

For a detailed API specification, including request parameters and response formats, please refer to our API Specification.

Getting Started

Step 1: Create a Service Account

Clients need to create a service account from the VGS Dashboard and share the Client-ID with VGS.

Instructions:

• Log in to the VGS Dashboard.

• Navigate to Vault → Organization → Service Account.

• Click on Create New.

• In the Create Service Account tab, enter the required information for the following fields:

  • Add Name: Enter a name for the Service Account.

  • Select Vaults: Select the vault(s) you want associated with this Service Account.

  • Select Scopes: organization-users:read.

• Click Create.

• Download the Client-ID and Client-Secret, which will be used for calling the API.

Step 2: Prepare API Call Inputs

Clients should have the following credentials ready before making an API call:

• organization-id: Unique organization identifier provided by VGS.

• client_id: Generated in Step 1.

• client_secret: Generated in Step 1.

Step 3: Make API Request

Connect to the API endpoint here https://accounts.apps.verygoodsecurity.com to make a request.

3.1 Get the Bearer token

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

Sample API response:

Note the access_token to use it in the subsequent call

{
  "access_token": "eyJhbGciOi...emW50I",
  "expires_in":1200,
  "refresh_expires_in":1500,
  "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "not-before-policy":1635446873,
  "session_state":"088ac536-fce0-4785-806c-bf7a72530c73",
  "scope": "aliases:delete aliases:write user_id organization-users:read service-account aliases:read"
}

3.2 Call the API using the Bearer token from step 3.1

Replace <access_token> with access_token value from the above call.

Replace <organization_id> with organization_id value as seen on the dashboard.

curl https://accounts.apps.verygoodsecurity.com/organizations/<organization_id>/members \
 -H "Authorization: Bearer <access_token>" \
 -H "Accept: application/vnd.api+json" 

Sample API response:

The following are the details of two sample users along with their permissions:

{
  "data" : [ {
    "id": "IDebbg52VnzYnfwyroS5XMw6",
    "type": "users",
    "attributes": {
      "created_at" : "2023-04-25T17:27:13"
      "id" : "IDebbg52VnzYnfwyroS5XMw6",
      "updated_at": null,
      "name": "John Doe",
      "email_address" : "[email protected]",
      "permissions" : [ "read", "write", "admin" ],
      "vaults" : [ {
        "id": "tntb4iawrkv",
        "name": "Test",
        "role": "admin",
        "env_identifier": "SANDBOX"
      } ],
      "role": "admin",
      "last_login": null,
      "last_ip": null,
      "sso_id": "MK343423"
    }
  }, {
    "id": "ID6cWBgb8GVi6FTcHTWaDKWM",
    "type": "users",
    "attributes": {
      "created_at": "2023-04-26T16:19:34",
      "updated_at": null,
      "id": "ID6cWBgb8GVi6FTcHTWaDKWM",
      "name": "Segun Bode",
      "email_address": "[email protected]",
      "permissions": [ "read", "write" ],
      "vaults": [ {
        "id": "tntb4iawrkv",
        "name": "Test",
        "role": "read",
        "env_identifier": "SANDBOX"
      } ],
      "role": "user",
      "last_login": null,
      "last_ip": null,
      "sso_id": "MK343419"
    }
  } ]
}

Support

For any issues, please reach out to [email protected].