Project the CALLING credential's authority over registered operations

POST

/v1/auth/capabilities

const url = 'https://example.com/v1/auth/capabilities';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"questions":[{"id":"example","kind":"surface","operation":"example","selectors":{"body":{"additionalProperty":"example"},"path":{"additionalProperty":"example"}},"workspace_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}],"schema_version":2}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/auth/capabilities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "questions": [ { "id": "example", "kind": "surface", "operation": "example", "selectors": { "body": { "additionalProperty": "example" }, "path": { "additionalProperty": "example" } }, "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" } ], "schema_version": 2 }'

Projects the CALLING credential’s authority over registered operations, up to 32 independent questions per batch. A surface question asks whether one registered collection may be loaded in the named workspace; an operation question asks whether one exact operation on one exact resource is authorized right now. It never executes the operation, so asking writes no row, no audit event and no expiry. UNKNOWN means the decision could not be established, never that a role is insufficient. A positive carries refresh_after_ms, the remaining evidence window capped at 30s: an observation budget, not a lease. The handler re-authorizes every real act.

Authorizations

bearerAuth
browserSession

Parameters

Header Parameters

X-Olivares-Tenant

string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Request Body^required

application/json

object

questions

required

Up to 32 independent questions. The limit protects one request; it does not cap the inventory of operations and does not prevent a later batch. Results stay independent per id — the batch never ANDs or ORs them, and its 200 never turns an unknown into a denial.

Array<object>

>= 1 items <= 32 items

object

required

Correlates this question with its result.

string

kind

required

surface asks whether this registered COLLECTION may be loaded at all in the named workspace. It asserts nothing about rows: an authorized empty list is reachable, and a not_reachable collection never denies an operation on another route. operation asks whether this exact operation on this exact resource is authorized right now.

string

Allowed values: surface operation

operation

required

METHOD <registered pattern>, e.g. GET /v1/m/sessions/channels/administration. It names a route as it is MOUNTED; it is never a resolved URL, and no HTTP call is made for it.

string

selectors

object

body

The ONE declared top-level body field an entity route uses to locate its row. It is an identification input, not a write payload: no other field of a command is admitted or consulted, and nothing is executed.

object

key

additional properties

string

path

The declared path locator of an entity route (its {id}).

object

key

additional properties

string

workspace_id

For a collection: the workspace selector the route declares, corroborated by the server against the stored workspace row. For an entity: an assertion COMPARED with the row’s stored workspace — a mismatch is answered with that route’s own concealment and is never silently corrected.

string format: uuid

schema_version

required

Contract version. Only 2 is accepted; version 1 and every other value are rejected with 400 before any question lookup.

integer

Allowed values: 2

Responses

200

application/json

object

results

required

Array<object>

object

code

required

not_permitted is an established non-concealing denial. not_disclosed accompanies undisclosed and carries no negative explanation. not_supported, inputs_required and step_up_required may accompany unknown only as target-free request gates on a concealing operation. Later authority failures, including unusable evidence, are not disclosed there. For other projections engine_unready and evidence_unavailable accompany unknown. stale is the CLIENT’s own verdict after expiry or context change; the server never sends it.

string

Allowed values: authorized admitted not_permitted not_disclosed not_supported inputs_required engine_unready evidence_unavailable step_up_required stale

required

string

kind

required

string

Allowed values: surface operation

observed_at

required

For undisclosed, the common batch dispatch marker, not an authority fact. Other results retain their own observation instant.

string format: date-time

refresh_after_ms

How long this POSITIVE may be shown, in milliseconds: the minimum of 30000 and what REMAINS of the evidence window of every predicate that founds it. It is present ONLY on allowed/reachable, and its ABSENCE on one is itself an instruction — treat that result as unknown rather than believing it. Discount the whole request with a MONOTONIC clock, including retries of the same question; a late response does not start a fresh window on arrival. It is an observation budget, NOT a lease: it grants nothing, and it does not promise that a revocation elsewhere will reach you within it. The handler re-authorizes every real act and accepts nothing from this response.

integer

state

required

Operations answer allowed, denied or unknown. A registered concealing operation instead publishes undisclosed for every nonpositive authority outcome: it asserts neither denial, absence nor outage. Target-free input/support/step-up rejections remain unknown. Surfaces answer reachable, not_reachable or unknown and confer no row authority. Only a fresh positive with its finite budget may enable an action; no other state is a permit.

string

Allowed values: allowed denied unknown undisclosed reachable not_reachable

schema_version

required

integer

Allowed values: 2

Example

{
  "results": [
    {
      "code": "authorized",
      "kind": "surface",
      "state": "allowed"
    }
  ],
  "schema_version": 2
}

400

Bad request

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

401

Unauthenticated

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

403

Forbidden

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

404

Not found

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

409

Conflict / setup required

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

429

Rate limited

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

503

Common authorization evidence is unavailable; no target was resolved

application/json

object

error

required

object

code

required

string

message

required

string

module

With code module_not_enabled: the namespace of the module this node does not run.

string

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "module": "example"
  }
}

Project the CALLING credential's authority over registered operations

Authorizations

Parameters

Header Parameters

Request Body required

Responses

200

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

409

Example generated

429

Example generated

503

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated