# Execute a tool

> Authenticated tool execution for Vigilbase One + CLI.

Source: https://docs.vigilbase.com/one/api/reference/tools/post-tools-tool-name-execute

`POST https://one.vigilbase.com/api/tools/{toolName}/execute`

Authenticated tool execution for Vigilbase One + CLI. Access is gated by requireToolRunAccessContext (read:services) — same bar as listing/viewing tool runs. write:services is reserved for mutating customer service integrations, not for launching scanners.

## Authorizations

Send one of these:

- `Authorization` (string, header, required): Bearer access token from Vigilbase Identity (`auth.vigilbase.com`), sent as `Authorization: Bearer <token>`. The CLI gets one with `vigilbase login`.
- `Authorization` (string, header, required): Organisation API key (`vb_one_…`) from **Settings → API keys** in Vigilbase One, sent as `Authorization: Bearer vb_one_…`. Needs a key with write access: read-only keys get `403` with the code `read_only_key`. See [organisation API keys](https://docs.vigilbase.com/one/api#organisation-api-keys).

## Path parameters

- `toolName` (string, required)

## Body (application/json)

- `target` (string, required): Min length 1.
- `metadata` (object)

## Responses

### 200

Success

### 401

Authentication required

### 403

Not permitted

## Example request

```bash
# Token from `vigilbase login`, or a write API key (vb_one_…)
curl --request POST \
  --url 'https://one.vigilbase.com/api/tools/{toolName}/execute' \
  --header "Authorization: Bearer $VIGILBASE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"target":"<string>","metadata":{}}'
```

With the Vigilbase CLI:

```bash
vigilbase run <tool> <target>
```

See also the [guide](https://docs.vigilbase.com/one/api/tool-runs).