Call a URL as this agent. The broker injects the credential. The vault secret is never in the response.

POST/v1/use

Authorization

AuthorizationBearer token (JWT) · headerrequired

Hydra JWT. Identity is the bound agent or a Keto member human. The host is not identity.

Request body

requiredapplication/json

itemstringrequired

Granted item name

urlstringrequired

Absolute URL. Host must match the item.

methodstring

default: "GET"

headersobject

Extra request headers. Never the vault secret.

bodystring

Request body. Never the vault secret. Use --body-file on the CLI.

body_b64string<byte>

Base64 request body for binary payloads. Takes precedence over body. Never the vault secret.

Responses

200Decision plus upstream result, scrubbed

decisionstringrequired

Allowed:allowdenyneed_approval

reasonstring

approval_idstring

request_idstring

The filed approval request when decision is need_approval. Owners resolve it via /v1/requests/{id}.

request_expires_atstring<date-time>

When the filed ask dies unanswered. Agents may keep retrying until then.

statusinteger

headersobject

Upstream response headers, including Content-Type and Content-Encoding.

bodystring

Upstream body with vault secrets scrubbed. Present when the body is valid UTF-8.

body_b64string<byte>

Base64 upstream body with vault secrets scrubbed. Present when the body is not valid UTF-8 (gzip, images, protobuf).

400bad request

401missing or invalid Bearer

Request

curl -X POST "https://veil.nyc/v1/use" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": "string",
  "url": "string",
  "method": "GET",
  "headers": {},
  "body": "string",
  "body_b64": "<byte>"
}'

const response = await fetch("https://veil.nyc/v1/use", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "item": "string",
  "url": "string",
  "method": "GET",
  "headers": {},
  "body": "string",
  "body_b64": "<byte>"
})
});

import requests

response = requests.post(
    "https://veil.nyc/v1/use",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    json={
  "item": "string",
  "url": "string",
  "method": "GET",
  "headers": {},
  "body": "string",
  "body_b64": "<byte>"
},
)

Response

{
  "decision": "allow",
  "reason": "string",
  "approval_id": "string",
  "request_id": "string",
  "request_expires_at": "2024-01-01T00:00:00Z",
  "status": 0,
  "headers": {},
  "body": "string",
  "body_b64": "<byte>"
}