Overview

The “UserAccount” resource type is used to sync user account information into Vanta.

Almost every system leverages user account provisioning, authentication, role definition, and more. By leveraging this resource, you can sync user account data into Vanta for your application. Vanta will treat these identically to user accounts obtained through a traditional Vanta built integration (ex. AWS IAM users, GitHub users, etc).

These accounts can be linked to the users Vanta pulls in from your Identity Provider, displayed in the Accounts page, performed Access Reviews on, monitored for changes in status and validated using custom tests.

Example

Create a new resource using the “UserAccount” resource type option. Give the resource a name and click “Create”. You can optionally adjust the schema by adding Custom Properties to fit your use case more accurately, but for the purposes of this guide we will just use the default schema.

Once created, grab the “Resource ID” as we’ll need it in the subsequent requests.

Next, we will learn how to List User Accounts resources.

Then we will Sync User Account resources to Vanta and confirm successful receipt.

Finally, we will GET User Accounts resources again to return all the resources we submitted in the previous step.

Once completed, we would have successfully exchanged User Accounts with Vanta, which will now be displayed in the Access page, and monitored by our Accounts Tests.

👍

Let's make our first User Account Resource API request next!

List User Accounts

GET Request

URL

Obtaining all the resources for a User Account base resource id, requires making a GET request to:

https://api.vanta.com/v1/resources/user_account

The base url api.vanta.com is the same we used to get our access token, but the rest of the path /v1/resources/user_account is used to get resources of User Account type.

📘

Any resources that are created using the Base Resource Type of User Accounts, will use the above endpoint to LIST all the resources from Vanta.

Parameters

In order to identify the exact resources we want to retrieve from the desired application, we will include the resource id as a parameter in the URL as follows:

https://api.vanta.com/v1/resources/user_account?resourceId={{accountResourceId}}

Headers

The last step before executing our request, is to configure the authorization. Vanta requires a Bearer Token to be passed in the header of the request, and the expected value is the one obtained during the Authorization flow.

Body

This request does not require any data in the body.

Summary

GET Response

Response Code

The expected response code for the above request is 200. This means everything was executed correctly. Any other response means there was an issue with the request. Review all the above steps, check the validity of your authorization token and retry your request.

Headers

Response headers can be ignored.

Body

A successful response will consist of an array of resources that follow the schema defined in Vanta for that resources or am empty array if no resources exist.

Summary

No Resources

Vanta does not have any resources for the given resource Id. This is expected if this is the first request we are making on this resource id, and no resources have yet been sent to Vanta via a SYNC request.

Assuming this guide has been followed in the established order, we have not sent any resources to Vanta, so expect to receive this response.

Resources Returned

Vanta has one or more resources for the given resource id. This means a successful SYNC request has already been sent to Vanta pushing a set of resources for Vanta to monitor.

Once you have completed the Sync User Accounts step, return here and rerun the above List User Accounts to list resources and confirm you are receiving all the resources sent before.

Assuming you have return here after syncing your resources, expect to receive this response.

👍

We have successfully listed all the resources from Vanta for a given resource id!

Sync User Accounts

PUT Request

🚧

Every PUT request to sync resources into Vanta provides a full state of available resources. This means, every resource to be monitored, needs to be sent with every SYNC request, otherwise, when a previously submitted resource is omitted in a subsequent SYNC, Vanta will assume that resource no longer exists and set it's "deletedAt" date to the time of the sync_all call

Note that deleted resources may still show up in certain parts of the product (eg: deleted users will be displayed as Deactivated on the access page)

URL

Sending all the resources for a User Account based resource id, requires making a PUT request to:

https://api.vanta.com/v1/resources/user_account

📘

Any resources that are created using the Base Resource Type of User Accounts, will use the above endpoint to SYNC all the resources to Vanta.

Parameters

This request does not require any parameters to be sent as part of the URL

Headers

This will be the same bearer token used in the GET request.

Body

This request requires a JSON Object to be sent in the body. This object will contain the resource Id to identify the resources that will be sent and the array of resources.

Each resource in the array needs to follow the defined schema for that resource id, as configured in the "Resources" page within the application you created.

We will continue to use the resource id from the UserAccount resource type we created earlier. Notice the resource id is included in the body of the request, as part of the JSON Object, and not in the URL as a parameter.

Summary

PUT Response

Response Code

The expected response code for the above request is 200. This means everything has executed correctly. Any other response means there was an issue with the request. Review all the above steps, check the validity of your authorization token and retry your request.

Headers

Response headers can be ignored.

Body

A successful response will consist of a JSON Object with only one property called success with a value of true. This indicates Vanta has successfully received and process your resources.

Summary

Check your work by making a new GET Request and confirming the GET Response contains all the resources you have just sent.

👍

We have successfully sent all our resources to Vanta for a given resource id.