> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vanta.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Auditor API
> Auditor API — programmatically conduct audits in Vanta: read audit data, manage information requests, and review evidence.
The Auditor API is for **audit firms** conducting audits of their customers' Vanta tenants. Use it to list active audits, pull controls and evidence, manage information requests, and review the resources, personnel, and monitored computers in scope for each engagement.
## Who is this API for?
This API is for **registered Vanta Audit Partners** — audit firms running SOC 2, ISO, HIPAA, and other engagements through Vanta. It is not available to Vanta customers automating their own tenant or to ISVs building marketplace integrations.
| You are... | Use this API to... |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **An audit firm / auditor** with a Vanta Audit Partner registration | List your active audits, pull controls and evidence, create and respond to information requests, and feed audit data into your own audit-management tooling. |
Don't see the **Auditor API** option in your Vanta navigation? Your firm needs to be set up as a Vanta Audit Partner first — contact your Vanta representative.
## When to use this API
Reach for Auditor endpoints when you want to:
* **List and inspect audits** assigned to your firm — pull controls, framework codes, in-scope people, and monitored computers.
* **Manage information requests (IRs)** programmatically — create custom IRs, accept or flag evidence, comment on items, and share the IR list with the customer.
* **Pull evidence** attached to audits and IRs into your own review workflow or audit-management platform.
* **Create custom controls and evidence requests** that supplement Vanta's built-in audit scaffolding.
New to the API? Walk through the [Conduct an Audit quickstart](/docs/quickstart/conduct-audit) to register an auditor application, get an access token, and list your first audit.
## Authentication
Auditor applications use the **`client_credentials`** OAuth flow. Create an application from the **Auditor API** section of the Vanta app (visible only to registered audit partners), then exchange your `client_id` / `client_secret` at the token endpoint for an access token scoped to your firm's audits.
| | |
| ---------------- | ------------------------------------------------------- |
| **Endpoint** | `POST /oauth/token` |
| **Base URL** | `https://api.vanta.com` · `https://api.vanta-gov.com` |
| **Content-Type** | `application/json` |
| **Grant type** | `client_credentials` |
**Request body**
| Field | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `client_id` | string | yes | OAuth client ID from your application on the **Auditor API** page in Vanta. |
| `client_secret` | string | yes | OAuth client secret from your application. |
| `scope` | string | yes | Space-separated list of [Auditor API scopes](#scopes), e.g. `auditor-api.audit:read`. |
| `grant_type` | string | yes | Must be `client_credentials`. |
```bash cURL theme={"system"}
curl --request POST 'https://api.vanta.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "vci_your_client_id",
"client_secret": "vcs_your_client_secret",
"scope": "auditor-api.audit:read",
"grant_type": "client_credentials"
}'
```
```javascript Node.js theme={"system"}
const response = await fetch("https://api.vanta.com/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: process.env.VANTA_CLIENT_ID,
client_secret: process.env.VANTA_CLIENT_SECRET,
scope: "auditor-api.audit:read",
grant_type: "client_credentials",
}),
});
const { access_token } = await response.json();
```
```python Python theme={"system"}
import requests
response = requests.post(
"https://api.vanta.com/oauth/token",
json={
"client_id": client_id,
"client_secret": client_secret,
"scope": "auditor-api.audit:read",
"grant_type": "client_credentials",
},
)
access_token = response.json()["access_token"]
```
**Response**
```json theme={"system"}
{
"access_token": "vat_...",
"expires_in": 3600,
"token_type": "Bearer"
}
```
| Field | Type | Description |
| -------------- | ------- | ---------------------------------------------------------------------------------- |
| `access_token` | string | Bearer token. Send as `Authorization: Bearer ` on every API request. |
| `expires_in` | integer | Lifetime in seconds. Always `3600` (1 hour). |
| `token_type` | string | Always `Bearer`. |
No `refresh_token` is issued. When the token expires after one hour, re-exchange your `client_id` / `client_secret` for a fresh one. For the full step-by-step setup, see the [Conduct an Audit quickstart](/docs/quickstart/conduct-audit).
**One active token per Application.** Requesting a new token with the same `client_id` / `client_secret` immediately revokes the previous one — any in-flight requests using the old token will fail with `401`. Centralize token issuance and don't run two processes that both mint tokens for the same application.
For grant-type tradeoffs, secret rotation, and other foot-guns, see [Authentication concepts](/docs/concepts/authentication).
## Scopes
| Scope | Grants |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `auditor-api.audit:read` | `GET` access to the [audit endpoints](/api-reference/audits/list-audits). |
| `auditor-api.audit:write` | Write access to the audit endpoints (create custom controls, manage IRs, accept evidence, etc.). |
| `auditor-api.auditor:read` | `GET` access to the [auditor endpoints](/api-reference/auditors/create-an-auditor). |
| `auditor-api.auditor:write` | Write access to the auditor endpoints. |
Request only the scopes your tool needs.
## Base URL
Use `https://api.vanta.com`, or `https://api.vanta-gov.com` if you're on Vanta Gov. See [Base URLs](/reference/overview#base-urls) for details.
## Pagination
List endpoints use cursor-based pagination via the `pageSize` and `pageCursor` query parameters.
To page through results:
1. Make the initial request, optionally setting `pageSize` (defaults vary by endpoint).
2. Check `results.pageInfo.hasNextPage` in the response.
3. If `true`, pass `results.pageInfo.endCursor` as the `pageCursor` in your next request.
4. Repeat until `hasNextPage` is `false`.
Responses are wrapped as:
```json theme={"system"}
{
"results": {
"data": [ /* ... */ ],
"pageInfo": {
"endCursor": "...",
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "..."
}
}
}
```
## Rate limits
The Auditor API is rate limited per OAuth client (your `client_id`) on a rolling 60-second window. Two limits apply:
* A **global cap of 600 requests / minute** across all Auditor API endpoints.
* A **per-endpoint limit** — some endpoints are more expensive than others, so they allow fewer requests per minute. Each endpoint's limit is documented on its own reference page.
A request is throttled when it exceeds either limit, whichever it reaches first. Exceeding a limit returns `429 Too Many Requests` — back off and retry after a short delay.
## Common workflows
Register an auditor application and pull your first audit data.
Enumerate the audits assigned to your firm.
Create, update, and accept evidence on IRs.
Pull evidence attached to controls and IRs.
## OpenAPI specification
Generate clients, import into your favorite tool, or browse the schema offline.
## Tools
Import the collection to explore endpoints quickly.
Official client libraries for the Vanta API.