OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
GET/v1/auth/whoami

Describe the authenticated principal

operation ID: get_v1_auth_whoami

Overview

Describe the authenticated principal. 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 describe the authenticated principal.
  • 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 GET \
  --url "$ORDINATE_URL/v1/auth/whoami" \
  --header "Authorization: Bearer $ORDINATE_TOKEN"

Expected output · 200

Authenticated principal and direct roles

Example 200 output

{
  "principal": "string",
  "display": "string",
  "kind": "string",
  "groups": [
    "string"
  ],
  "roles": [
    {
      "role": "string",
      "scope_kind": "string",
      "scope_id": "00000000-0000-4000-8000-000000000001"
    }
  ],
  "session_expires_at_ns": 0,
  "session_expires_at_ns_exact": "1785067200000000000",
  "effective_capabilities": [
    "string"
  ],
  "authorization_snapshot_built_at_ns": "1785067200000000000",
  "authorization_model_tx": "1785067200000000000",
  "capability_catalog_version": 1,
  "auth_mode": "disabled",
  "login_methods": [
    "local"
  ]
}

The cURL request supplies the documented path and query values and asks OrdinateDB to describe the authenticated principal. The documented 200 response is authenticated principal and direct roles.

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

Parameters

No parameters.

Request body

This operation has no request body.

Responses

200Authenticated principal and direct roles

application/json

auth_modestringrequired
authorization_model_txstringrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$
authorization_snapshot_built_at_nsstringrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$
capability_catalog_versionintegerrequired
minimum: 1
displaystringrequired
effective_capabilitiesarrayrequired
unique items

array

string

Extensible capability token. Unknown future tokens remain parseable but do not enable controls the client does not understand.

pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$
groupsarrayrequired

array

string
kindstringrequired
login_methodsarrayrequired
unique items

array

string

values: local · oidc

principalPrincipalStringrequired
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:.+)$
rolesarrayrequired

array

rolestringrequired
scope_idstringrequired
format: uuid
scope_kindstringrequired
unknown fields rejected
session_expires_at_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null
session_expires_at_ns_exactstring | nullrequired

Exact signed 64-bit integer encoded as a decimal string

pattern: ^-?[0-9]+$
unknown fields rejected

Example 200 output

{
  "principal": "string",
  "display": "string",
  "kind": "string",
  "groups": [
    "string"
  ],
  "roles": [
    {
      "role": "string",
      "scope_kind": "string",
      "scope_id": "00000000-0000-4000-8000-000000000001"
    }
  ],
  "session_expires_at_ns": 0,
  "session_expires_at_ns_exact": "1785067200000000000",
  "effective_capabilities": [
    "string"
  ],
  "authorization_snapshot_built_at_ns": "1785067200000000000",
  "authorization_model_tx": "1785067200000000000",
  "capability_catalog_version": 1,
  "auth_mode": "disabled",
  "login_methods": [
    "local"
  ]
}
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"
}
404Principal not found

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 404 output

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

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/whoami`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${token}`
  }
});

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

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

Related topics