> ## Documentation Index
> Fetch the complete documentation index at: https://vida.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Create a Vida API token and use it with the correct authorized account scope.

To use the Vida API, create an API key at the narrowest account scope that can complete your work:

* For one Agent, open that Agent and go to **Settings → Developer → API Keys**.
* For a reseller and its authorized downstream customers, go to **For Developers → API Keys** in the reseller workspace.
* For an eligible partner and its resellers, go to **Settings → Advanced → API Keys** in the partner workspace.

Select **New Key**, give it a recognizable purpose, and copy it to a secure environment or secret manager. API access may require an eligible paid plan. Never expose a key in client-side code, shared files, or chat.

Pass the key in the `token` query parameter:

```text theme={null}
https://api.vida.dev/api/v2/account?token={token}
```

Vida API tokens are not Bearer tokens. Treat each token as a credential and rotate it if it is exposed.

## Identify the key's account scope

Before selecting another account, call `GET /api/v2/account` without `targetAccountId`:

```bash theme={null}
curl -s "https://api.vida.dev/api/v2/account?token=$VIDA_API_KEY"
```

This response describes the account that owns the key. Identify its ordinary hierarchy scope using
the first matching rule:

1. `accountType` is `partner`, or `organizationId` matches `partnerId`: the key has Partner Admin
   scope.
2. `accountType` is `reseller`, or `organizationId` matches `resellerId`: the key has Reseller Admin
   scope.
3. `accountType` is `account`: the key is scoped to that Agent account.
4. `accountType` is `organization`, or it is a remaining `user` account with an `organizationId`:
   the key has Organization Admin scope.

The ID comparisons account for human members whose returned `accountType` is `user`. If the
response includes a nonempty `permittedAccountIds` list, that member is restricted to those child
accounts. Do not infer broader access from the member's email address, username, or employer.

Account scope identifies where the key may act; it does not guarantee every operation is available.
Account status, plan, enabled features, selected target, and endpoint-specific requirements still
apply. Verify only the read operation needed for the work instead of probing unrelated endpoints to
infer privileges.

All API endpoints accept an optional `targetAccountId` query parameter for delegated scope. When provided by a higher-level account token, the request executes in the context of an authorized child account in that caller's hierarchy.

For example, a Reseller token can use `targetAccountId=<organizationId-or-agentId>` to act on that Organization or Agent when it belongs to the Reseller. Requests for an unrelated account are rejected.

Some routes include the selected account directly in the path, such as `/api/v2/computer/accounts/{targetAccountId}`. Do not also send a different `targetAccountId` in the query or request body.

Keep the original untargeted account response separate from later targeted reads. A request with
`targetAccountId` describes the selected account; it does not redefine the key owner's scope.

`targetOrganizationId`, `targetResellerId`, and `targetPartnerId` are used by endpoints whose resource is explicitly scoped at those levels. Follow the endpoint schema rather than substituting a different identifier.

For additional help, email [help@vida.inc](mailto:help@vida.inc).