OrdinateDB

Documentation

product Pre-releaseunwritten sections are marked
PUT/v1/auth/roles/{id}

Update or retire an authorization role

operation ID: put_v1_auth_roles_by_id

Overview

Update or retire an authorization role. 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 update or retire an authorization role.
  • 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 PUT \
  --url "$ORDINATE_URL/v1/auth/roles/00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{}'

Expected output · 200

Updated role

Example 200 output

{
  "role_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "capabilities": [
    "read"
  ],
  "system": false,
  "valid_from_ns": 0,
  "valid_to_ns": 0,
  "tx_id": 0
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to update or retire an authorization role. The documented 200 response is updated role.

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
admin
Authorization scope
handler-resolved target

Parameters

NameInRequiredType and constraints
idpathyes
stringformat: uuid

Request body

application/json

capabilitiesarrayoptional

array

Capability
string

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

expected_txintegeroptional
format: int64
namestringoptional
retiredbooleanoptional
unknown fields rejected

Example request body

{}

Responses

200Updated role

application/json

capabilitiesarrayrequired

array

Capability
string

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

namestringrequired
role_idstringrequired
format: uuid
systembooleanrequired
tx_idintegerrequired
format: int64
valid_from_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64
valid_to_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null
unknown fields rejected

Example 200 output

{
  "role_id": "00000000-0000-4000-8000-000000000001",
  "name": "string",
  "capabilities": [
    "read"
  ],
  "system": false,
  "valid_from_ns": 0,
  "valid_to_ns": 0,
  "tx_id": 0
}
204Role retired

No response body.

400Invalid 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"
}
403Required capability is not granted

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"
}
404Role 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"
}
409Transaction conflict or duplicate name

application/json

ErrorEnvelope
codestringrequired
correlation_idstringrequired
format: uuid
detailsobjectoptional
errorstringrequired

Example 409 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/roles/00000000-0000-4000-8000-000000000001`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({})
});

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

const data = response.status === 204 ? null : await response.json();
console.log(data);

Related topics