Skip to content
KataraKatara documentation

Begin a reviewed OAuth authorization

POST
/katara/v1/orgs/{org_id}/environments/{environment_id}/tool-credentials/oauth/authorizations
curl --request POST \
  --url https://api.katara.com/katara/v1/orgs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/environments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/tool-credentials/oauth/authorizations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-Katara-CSRF: 1' \
  --data '{ "profile": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" }, "owner_kind": "user", "agents": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ], "reconnect": { "connection_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "expected": { "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": 1, "integrity": "example" } }, "authorization_expires_at": "2026-04-15T12:00:00Z" }'

Requires the current human session and exact environment authority. Begin and activate require caller idempotency keys; Complete uses the durable one-use authorization ID and no idempotency header. No automatic retries or provider exchange replay. The Start response pins organization, environment, mode, reset generation and profile before navigation. Never persist or log its URL/state, callback code, original sensitive error or token response. After unknown completion inspect Review. oauth_exchange_uncertain (409) requires inspection, not retry; oauth_authorization_rejected (403) requires a new authorization. Activation requires explicit review of the verified account digest. Tokens never leave protected service storage. All routes reject query parameters. Begin requires an explicitly reviewed authorization_expires_at, strictly future and within the enrolled profile max_authorization_seconds. Start and Review echo that immutable authority deadline. The separate expires_at is the 10-minute setup/review window. Serialized private token refresh never extends the connection authority deadline.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
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

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
/^[A-Za-z0-9._:-]{8,128}$/
X-Katara-CSRF
Allowed value: 1

Browser cookie mutations require value 1 and an allowed Origin. Session bearer clients may omit this header.

X-Katara-Account-ID
string format: uuid
/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/

Required for cookie-authenticated changes. Use the UUID of the account that loaded the application. A different current cookie account returns account_changed before the handler runs. Session bearer and API key clients do not require this header.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
profile
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}$/
owner_kind
required
Allowed values: user organization
agents
required
Array<string>
>= 1 items <= 32 items unique items
reconnect
object
connection_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
expected
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}$/
authorization_expires_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,6}0{0,3})?Z$/

Responses

Section titled “Responses”

201

Section titled “201”

OAuth metadata; no access or refresh tokens.

Media typeapplication/json
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
mode
required
Allowed values: test live
reset_generation
required
integer
>= 1 <= 9007199254740991
profile
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}$/
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
authorization_url
required

Sensitive one-time authorization redirect. Do not log or persist the URL or its state. Validate scope, profile and issuer before explicit navigation.

string format: uri
<= 32768 characters /^https:///
expires_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?Z$/
authorization_expires_at
required
string format: date-time
/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,6}0{0,3})?Z$/
Example
{
  "mode": "test"
}

Headers

Section titled “Headers”
Cache-Control
string
Allowed value: no-store
Referrer-Policy
string
Allowed value: no-referrer

409

Section titled “409”

Account_changed: reload and review with the signed-in account.

default

Section titled “default”

Request error

Media typeapplication/json
object
error
required
object
message
required
string
>= 1 characters <= 500 characters
type
required
string
>= 1 characters <= 100 characters
code
required

Stable; branch on it. Any operation can answer invalid_request, with param naming the refused field when there is one; human_session_required, when an API key, service account or workload calls an operation only a signed-in person may perform; reauthentication_required, when a person’s sign-in is too old for the operation; permission_denied; route_not_found and method_not_allowed, when no operation matches the path or method; and feature_unavailable, when the operation’s service is not enabled on this deployment.

string
>= 1 characters <= 100 characters
param
required

The request field a refusal is about, such as the agent_id or run_id query parameter; null when the refusal is not about one field.

string | null
request_id
required
string
>= 1 characters <= 100 characters
upstream_status
required
integer | null
action
Allowed values: sign_in reauthenticate request_access review fund retry reconcile refresh support
operation_id
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
snapshot_ref
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
Example
{
  "error": {
    "action": "sign_in"
  }
}