API access
TL;DR
- Instead of asking for a secret, a workflow or agent asks the Vault to make the API call with it:
vault.http.request. - The caller gets the response, with the secret removed. It never sees the value.
- It works only for secrets an owner or admin has given API access: which hosts, which methods, and how the secret is sent.
1. Turn on API access for a secret
In the Console: Vault → Secrets, open the secret's Manage menu and choose API access…. Fill in the allowed hosts, the methods and how to send the secret, then use Test call to check it.
From the API, an owner or admin calls vault.secret.usage.set:
{
"path": "github/ci/token",
"usage": {
"allowed_hosts": ["api.github.com"],
"methods": ["GET", "POST"],
"placement": { "kind": "header", "name": "Authorization", "template": "Bearer {value}" }
}
}
| Field | Meaning |
|---|---|
allowed_hosts | Up to 20 hostnames, such as api.stripe.com. List each host exactly; add :port if it is not 443 |
methods | Any of GET, HEAD, POST, PUT, PATCH, DELETE. Default GET |
placement | How the secret is sent (below) |
placement.kind | Sends the secret as |
|---|---|
header | A header, such as Authorization with Bearer {value} |
basic | Basic auth, with the username you give and the secret as the password |
query | A query parameter, such as api_key |
Set usage to null to turn API access off. The secret itself is kept.
2. Give the caller use
The member or Staff agent needs the use permission on the secret. Add a policy. use does not let them read the value.
3. Make the call
Start vault.http.request:
| Input | Meaning |
|---|---|
path | The secret to use |
method | One of the allowed methods |
url | An https URL on an allowed host |
headers | Optional extra headers |
body | Optional request body, up to 256 KiB |
timeout_seconds | Default 15, at most 30 |
You get back response_status_code, the main response_headers, and response_body (up to 1 MiB) with any copy of the secret replaced by [REDACTED]. If the API echoes the secret back in another form, the body is withheld and body_withheld is true.
When a call is refused
- The secret has no API access, or the host or method is not allowed.
- The URL is not
https, or points to a private or internal address. - The secret is shorter than 8 characters.
- Too many calls are running for your organization at once. Try again shortly.
Every call, allowed or refused, is recorded in the audit log.
In workflows and agents
vault.http.request can be a step in a composed workflow, and Staff agents can start it like any other workflow. Permissions are checked against the person or agent behind the run.