OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
POST/v1/auth/effective

Explain an effective authorization decision

operation ID: post_v1_auth_effective

Overview

Explain an effective authorization decision. The authentication API establishes identity and manages the roles, grants, sessions, and service credentials used for authorization.

When to use it

  • Use it when an application needs to explain an effective authorization decision.
  • Use it when a client needs to sign in, inspect its identity, or an administrator needs to manage access.

Quick example

Set the base URL and replace generated identifiers or credentials with values from your installation.

cURL

curl --request POST \
  --url "$ORDINATE_URL/v1/auth/effective" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "capability": "read",
    "scope_kind": "site",
    "scope_id": "00000000-0000-4000-8000-000000000001"
  }'

Expected output · 200

Decision from the same evaluator used for enforcement

Example 200 output

{
  "allowed": false,
  "derivation": [
    {}
  ],
  "snapshot_built_at_ns": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to explain an effective authorization decision. The documented 200 response is decision from the same evaluator used for enforcement.

How it works

OrdinateDB resolves a session or bearer credential to a principal, then evaluates roles, capabilities, and resource scope for each protected operation.

Reference

Required capability
authenticated
Authorization scope
self, or any principal with admin

Parameters

No parameters.

Request body

application/json

as_of_nsintegeroptional

UTC Unix timestamp in nanoseconds

format: int64
capabilityCapabilityrequired
Capability
string

values: read · annotate · enter · approve · amend · model-edit · registry-manage · calc-author · display-author · display-publish · episode-manage · redact · admin

principalany ofoptional

any of

option 1

PrincipalString
string

Grant-subject grammar: system, user UUID, service UUID, or an IdP group name.

pattern: ^(system|(user|svc):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|group:.+)$

option 2

null
scope_idstringrequired
format: uuid
scope_kindstringrequired
unknown fields rejected

Example request body

{
  "capability": "read",
  "scope_kind": "site",
  "scope_id": "00000000-0000-4000-8000-000000000001"
}

Responses

200Decision from the same evaluator used for enforcement

application/json

allowedbooleanrequired
derivationarrayrequired

array

object with arbitrary properties

group_membershipstringoptional
snapshot_built_at_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
unknown fields rejected

Example 200 output

{
  "allowed": false,
  "derivation": [
    {}
  ],
  "snapshot_built_at_ns": 0
}
400Invalid decision request

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 400 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
401Authentication required

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 401 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
403Admin capability required for another principal

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 403 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}
503Model database is not configured

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 503 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

Code examples

These examples are generated from the source contract. Replace the base URL, credentials, identifiers, and minimal generated values for your instance.

JavaScript

const ordinateUrl = "http://localhost:8080";
const token = "<bearer-token>";

const response = await fetch(`${ordinateUrl}/v1/auth/effective`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "capability": "read",
  "scope_kind": "site",
  "scope_id": "00000000-0000-4000-8000-000000000001"
})
});

if (!response.ok) {
  throw new Error(`OrdinateDB returned ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data);

Related topics