Skip to content
KataraKatara documentation

Ask what admission would decide for an action

POST
/katara/v1/orgs/{org}/environments/{environment}/actions:authorize
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/actions:authorize \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "tool": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" }, "arguments": { "org_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "environment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example", "media_type": "text/plain", "size_bytes": 1 }, "grant_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "budget_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expires_at": "2026-04-15T12:00:00Z" }'

For an external agent’s key. Runs the grant check, the active policy and the detectors against the action the catalog would build, and records nothing. The answer is advisory: it is not a token, and submitting asks again.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org
required
string format: uuid
environment
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

One published tool version, arguments already stored as content, and the grant and budget the action is taken under. Destination, effect and cost come from the catalog.

object
tool
required
object
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
arguments
required
object
org_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
environment_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
version
required
integer
>= 1 <= 9223372036854776000
integrity
required
string
/^sha256:[a-f0-9]{64}$/
media_type
required
Allowed values: text/plain text/markdown application/json application/pdf application/vnd.openxmlformats-officedocument.wordprocessingml.document image/png image/jpeg text/csv application/zip
size_bytes
required
integer
<= 104857600
grant_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
budget_id
required
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
Allowed value: 00000000-0000-0000-0000-000000000000
expires_at
required
string format: date-time

Responses

Section titled “Responses”

200

Section titled “200”

What admission would decide now; nothing is recorded.

Media typeapplication/json
object
outcome
required
Allowed values: allow deny require_approval
reasons
required
Array<string>
<= 32 items
Example
{
  "outcome": "allow"
}

400

Section titled “400”

The request is malformed or names what the catalog decides.

403

Section titled “403”

The key is not an external agent’s, or its grant, policy or budget refuses the action.

404

Section titled “404”

The tool version, grant or budget is unavailable in this environment.

409

Section titled “409”

Managed_run_required: the tool needs a Katara-held credential or a price. conflict: the id names another action.

500

Section titled “500”

The action or its authority could not be checked.