NetFoundry Authorization Service

Overview — What Does This Service Do?

The Authorization Service is the single source of truth for who can do what in the NetFoundry platform. It answers two fundamental questions:

• Does Alice have permission to read network xyz-789?
• Does the Network Service have permission to create an endpoint under network xyz-789?

It does this through three responsibilities:

Domains

A Domain is the primary segregation boundary in the permission model. It is a namespace that says: "these resource types and their actions belong together and are owned by one microservice area."

Domain Is a Hard Wall

Every authorization check starts by matching the domain code. A grant in io.netfoundry.network is completely invisible when checking an io.netfoundry.identity action. You cannot cross domain boundaries with a single grant.

Authorization.isAuthorized(
    identityId,
    authorizationSet,
    "io.netfoundry.network",   // ← domain code matched first
    "network",                 // ← then resource type code
    "read",                    // ← then action code
    targetPath
);

This means "Org Admin" (a grant in the identity domain) gives zero network permissions, and "Network Group Admin" (a grant in the network domain) gives zero identity permissions. They are separate grants in separate domains. See Org Admin Explained for a full walkthrough.

All Domains in the System

Domains are seeded by Flyway migration and never change at runtime. There are 7 in the system:

How the Layers Build Up

Every permission in the system is ultimately described by these four layers, each narrowing the scope further:

All four are seeded once by Flyway migration and never change at runtime. They define the vocabulary of what can be protected. StandardRoles and grants then use this vocabulary to express who can do what.

Domain and SuperUser Scoping

The SuperUser table has a nullable domainId column. This lets you create a super-user scoped to a single domain:

SuperUser { identityId = alice-uuid, domainId = null }
  → Full access to every resource in every domain (platform root)

SuperUser { identityId = bob-uuid, domainId = <id of io.netfoundry.network> }
  → Full access to all network resources only; zero access to identity or billing

Resource Types

A Resource Type defines a category of things that can be acted upon within a domain. Resource types form a tree via the parentId column — a root type has parentId = null, and child types point to their parent.

The tree defines containment: a network lives inside a network-group, an endpoint lives inside a network. The depth of a resource type in the tree drives the above / at / below logic used by every authorization check.

Identity Domain Tree

An "Org Admin" grant is at depth 0. All identities are at depth 1 — they are "below" the grant, so Admin's create / delete (includeWhenBelow=true) rules apply to them.

Network Domain Tree

How Depth Controls What a Grant Covers

When you hold a StandardRole grant, the path in that role is at a specific depth. The depth of the action's resource type relative to the grant's resource type determines which ActionInclusion flag applies:

Resource Actions

A Resource Action is something that can be performed on a Resource Type. Every resource type gets four standard CRUD actions automatically, plus any custom actions added later.

Standard Actions (auto-created for every resource type)

Custom Actions (examples)

Resource Paths — The Heart of Authorization

A ResourceIdPath is a chain of (resourceType, UUID) pairs from the root of a resource tree down to a specific resource. It looks conceptually like:

network-group/<ng-uuid> → network/<net-uuid> → endpoint/<ep-uuid>

How path matching works

When checking authorization, the system compares the identity's grant path against the target resource path:

Organizations

An Organization is the top-level container in the identity domain. It is a ResourceType with code organization in domain io.netfoundry.identity.

Everything in the NetFoundry platform is scoped to an organization. Networks, users, API accounts — they all "belong to" an organization at the top of their resource path.

In the network domain, a NetworkGroup is also scoped to an organization. So the full path to a network looks like:

organization/org-abc-123 → network-group/ng-xyz → network/net-789

Users and Identities

In NetFoundry, Identity is the abstract concept — a UUID-based principal that can hold grants. There are several concrete identity types:

All three types share the same authorization model. A User Identity and an API Account Identity can hold the same kinds of grants — Standard Roles, Custom Roles, direct action grants, etc.

How a new user is set up under an organization

Grant Types — How Permissions Are Assigned

A Grant is an assignment of a permission to an identity. There are five grant types, evaluated in priority order. The first type that authorizes the action wins.

SuperUser Grant

Database structure

SuperUser {
  id         binary(16)   -- grant UUID
  identityId binary(16)   -- the identity this applies to
  domainId   binary(16)   -- NULL = all domains; set = only that domain
}

• If domainId is NULL → super-user over everything (all domains, all resources)
• If domainId is set → super-user only within that domain

-- Give Alice's identity full super-user access across all domains
SET @identityId = UNHEX('87756049EBD311EAB3FE0242C0A8900C');  -- Alice's identity UUID

INSERT INTO SuperUser (id, identityId, domainId) VALUES (
    UNHEX(REPLACE(UUID(), '-', '')),
    @identityId,
    null  -- null = all domains
);

POST /auth/v1/super-users
Authorization: Bearer <NF JWT of an existing super-user>
Content-Type: application/json

{
  "identityId": "87756049-ebd3-11ea-b3fe-0242c0a8900c",
  "domainId": null
}

Public Grant

Database structure

PublicGrant {
  id               binary(16)
  resourceActionId binary(16)  -- which action is being granted
  isAnonymous      BIT          -- true = even unauthenticated callers get this
}

What is publicly granted by default?

-- Make "read" on a new resource type publicly accessible to all authenticated users
POST /auth/v1/public-grants
Authorization: Bearer <NF JWT>

{
  "resourceActionId": "the-uuid-of-the-read-action-on-your-resource-type",
  "isAnonymous": false
}

Identity-Resource Action Grant

Use this when you need to grant one precise permission without giving a whole role. For example: "Alice can reset MFA for users in organization ABC, but nothing else."

POST /identity-resource-actions
Authorization: Bearer <NF JWT>

{
  "identityId": "alice-uuid",
  "resourceActionId": "uuid-of-update-reset-mfa-action",
  "resourceIdPath": [
    { "resourceTypeId": "uuid-of-organization-resource-type", "resourceId": "org-abc-uuid" }
  ]
}

POST /identity-resource-actions
Authorization: Bearer <NF JWT>

{
  "identityId": "network-service-identity-uuid",
  "resourceActionId": "uuid-of-network-create-action",
  "resourceIdPath": []   // empty path = permission on ALL networks globally
}

Custom Role

Structure

CustomRole {
  id   binary(16)
  name varchar(256)     -- e.g., "Read-Only, ALL Auth Domain Resources"
}

CustomRoleAction {
  customRoleId     → CustomRole.id
  resourceActionId → ResourceAction.id
  -- optional: CustomRoleActionResourceAncestry for path scoping per action
}

IdentityCustomRole {
  identityId   binary(16)   -- who gets this role
  customRoleId binary(16)   -- which role
  -- optional: ancestry rows for path scoping
}

Well-Known Custom Roles

// Step 1: Create the custom role
POST /auth/v1/custom-roles
{
  "name": "Network Read plus Edge Router Heal"
}
// Response: { "id": "new-custom-role-uuid", "name": "..." }

// Step 2: Add actions to the role
POST /auth/v1/custom-role-actions
{
  "customRoleId": "new-custom-role-uuid",
  "resourceActionId": "uuid-of-network-read-action"
}
POST /auth/v1/custom-role-actions
{
  "customRoleId": "new-custom-role-uuid",
  "resourceActionId": "uuid-of-edge-router-update-heal-action"
}

// Step 3: Grant the role to Bob over a specific network group
POST /auth/v1/custom-role-grants
{
  "identityId": "bob-uuid",
  "customRoleId": "new-custom-role-uuid",
  "resourceIdPath": [
    { "resourceTypeId": "network-group-type-uuid", "resourceId": "ng-uuid" }
  ]
}

Standard Role

The most commonly used grant for end-users. Before looking at the DB rows, start with a real-world analogy — it makes every table name obvious.

The Analogy — University Building Management

Think of a university building management system:

The Seven Layers — Each One Narrows the Scope

Layer 1 — Domain: The Namespace Fence

A Domain owns a category of resources. Grants in one domain are invisible to checks in another — they are hard walls. The auth check always matches domain code first.

io.netfoundry.identity  → Identity Service  (orgs, users, API accounts)
io.netfoundry.network   → Core Service       (network-groups, networks, endpoints)
io.netfoundry.auth      → Auth Service       (roles, grants, actions — the model itself)
io.netfoundry.billing   → Billing Service    (billing accounts)

Layer 2 — ResourceType: The Shape of Things Inside a Domain

Resource types form a tree via parentId. The depth of a type in the tree is what drives which includeWhenAbove / At / Below flag applies during a permission check.

network-group  (depth 0 — root)
  └── network  (depth 1)
        ├── endpoint  (depth 2)
        ├── service   (depth 2)
        └── appwan    (depth 2)

Layer 3 — ResourceAction: The Verbs

Each ResourceType gets a set of actions. Default: create, read, update, delete. Custom actions like ziti-token-exchange or launch-diagnostics are added per type as needed. A create on network is a different row from create on endpoint.

Layer 4 — ActionInclusion: Rules Connecting Verbs to Strategy Names

This table says: for a given action and strategy name ("Admin" or "Read-Only"), should the action be included when the grant is above, at, or below the action's resource type? There are no per-identity or per-resource rows here — these are global rules seeded once by migration.

Action: read,   strategy: Admin    → above=✅  at=✅  below=✅
Action: create, strategy: Admin    → above=❌  at=❌  below=✅
Action: update, strategy: Admin    → above=❌  at=✅  below=✅
Action: delete, strategy: Admin    → above=❌  at=❌  below=✅
Action: read,   strategy: Read-Only → above=✅  at=✅  below=✅

Layer 5 — StandardRoleType: The Job Description

Combines a ResourceType with a strategy name. Answers: "what does it mean to be Admin on a network-group?" No paths, no identities, no resource instances — pure definition. One row per (resource type, strategy) pair. Seeded by migration, never changes.

StandardRoleType { resourceTypeId → network-group,  authorizationStrategyName = "Admin"    }
StandardRoleType { resourceTypeId → network-group,  authorizationStrategyName = "Read-Only" }
StandardRoleType { resourceTypeId → organization,   authorizationStrategyName = "Admin"    }
StandardRoleType { resourceTypeId → network,        authorizationStrategyName = "Admin"    }

Layer 6 — StandardRole: The Job Pinned to One Specific Resource

Takes the abstract definition and stamps it onto a real resource UUID. One row per (type, resource) pair. Created when a customer is provisioned — not by migration.

StandardRoleType (Admin on network-group)   ← shared by all customers
       ↓ stamped onto ACME's network-group
StandardRole { standardRoleTypeId → above }
StandardRoleResourceAncestry { resourceId = ng-acme-uuid }

Layer 7 — IdentityStandardRole: The Assignment

The leaf. Connects one identity to one StandardRole. This is the only row that ties a person to a permission. Everything above it is shared infrastructure.

IdentityStandardRole { identityId = alice-uuid, standardRoleId = sr-ng-acme }

Why Each Layer Exists

The Three Questions a Standard Role Answers

Concrete Example — Alice is Admin of ACME's Network Group

Row 1 — StandardRoleType (seeded by migration, exists forever)

StandardRoleType
  id                        = fad425e6-...
  resourceTypeId            = <id of "network-group" resource type>
  authorizationStrategyName = "Admin"

This row says: "the concept of being Admin on a network-group exists." Nothing about ACME. Nothing about Alice. It is a definition — written once by migration, never touched again.

Row 2 — StandardRole + StandardRoleResourceAncestry (created when ACME is provisioned)

StandardRole
  id                = sr-abc-123
  standardRoleTypeId = fad425e6-...      ← points to Row 1

StandardRoleResourceAncestry
  standardRoleId = sr-abc-123
  resourceId     = ng-acme-uuid          ← THIS makes it specific to ACME

This row says: "Admin-on-network-group, specifically on ACME's network group." Still nothing about Alice. This row is created once when ACME is provisioned. If Alice, Bob, and Carol all need Admin on ACME — they all share this same row.

Row 3 — IdentityStandardRole (created when Alice is granted access)

IdentityStandardRole
  id             = srg-xyz-789
  identityId     = alice-uuid            ← Alice
  standardRoleId = sr-abc-123            ← points to Row 2

This row says: "Alice holds the Admin-on-ACME's-network-group role." This is the only row that connects an identity to a permission. Everything above it is shared infrastructure.

Why Three Rows Instead of One?

You might ask: why not just one row that says { alice, Admin, ng-acme }?

Because 50 users might all need Admin on ACME. Without this split you would have 50 copies of "Admin on ng-acme" — the same information repeated 50 times.

With the split:

  StandardRole row (shared):
    sr-abc-123  →  Admin on ng-acme           ← 1 row for all 50 people

  IdentityStandardRole rows (one per person):
    alice  →  sr-abc-123
    bob    →  sr-abc-123
    carol  →  sr-abc-123
    ... 50 people ...  →  sr-abc-123

The "what resource, what strategy" is stored ONCE.
The "who has it" is stored 50 times — because that is the part that actually differs.

What Happens When a Second Customer (Globex) Is Provisioned?

A new StandardRole row is created for Globex, but it reuses the same StandardRoleType:

StandardRoleType fad425e6  (Admin on network-group)  ← shared by everyone, unchanged
       ↓                                    ↓
StandardRole sr-abc-123                StandardRole sr-def-456
  ancestry: ng-acme-uuid                 ancestry: ng-globex-uuid

IdentityStandardRole:                  IdentityStandardRole:
  alice  →  sr-abc-123                   dave  →  sr-def-456
  bob    →  sr-abc-123

Alice and Bob have no access to Globex. Dave has no access to ACME. The StandardRoleType definition is shared by both — but the StandardRole instances are separate, scoped to different resources.

Built-in Standard Role Types

The Full Chain in One Picture

StandardRoleType
  (Admin on network-group)        ← seeded by migration, shared by all customers
       ↓ referenced by
StandardRole
  (Admin on ng-acme specifically) ← created when ACME is provisioned
       ↓ referenced by
IdentityStandardRole
  (Alice holds that role)         ← created when Alice is granted access

Granting Alice Admin on NG-ACME via REST

// Step 1 — Find the StandardRoleType id (or know it already — these are stable)
GET /auth/v1/standard-role-types
// → find id for (network-group, Admin): "fad425e6-..."

// Step 2 — Create (or find) the StandardRole instance for ng-acme
POST /auth/v1/standard-roles
{
  "standardRoleTypeId": "fad425e6-...",
  "path": "io.netfoundry.network:network-group:ng-acme-uuid"
}
// → { "id": "sr-abc-123", ... }
// Idempotent: if the role for ng-acme already exists, the existing one is returned.

// Step 3 — Assign it to Alice
POST /auth/v1/standard-role-grants
{
  "standardRoleId": "sr-abc-123",
  "identityId":     "alice-uuid"
}

Action Inclusions — How Standard Roles Know What They Grant

Standard Roles don't have an explicit list of actions. Instead, the actions are derived from Action Inclusions — rules that say "if you have the Admin strategy on a resource, you implicitly have the create action on its children."

Action Inclusion Structure

ActionInclusion {
  resourceActionId          -- the action being conditionally included
  authorizationStrategyName -- "Admin" or "Read-Only"
  includeWhenAbove BIT      -- include this action if grant is ABOVE the resource
  includeWhenAt    BIT      -- include this action if grant is AT the resource
  includeWhenBelow BIT      -- include this action if grant is BELOW the resource
}

Default inclusion rules (applied to every resource type)

Complete Example: How Alice Gets Access to Resources

Alice is a new employee at ACME Corp. She needs to manage networks in ACME's network group NG-ACME. Here is the complete journey from zero to authorized.

Step 1 — Org admin invites Alice

POST https://gateway.staging.netfoundry.io/identity/v1/user-identities
Authorization: Bearer <org-admin's NF JWT>

{
  "email": "alice@acme.com",
  "firstName": "Alice",
  "organizationId": "acme-org-uuid"
}

Step 2 — Admin grants Alice "Network Admin" on NG-ACME

// Find the standard role type for Network Group Admin
GET /auth/v1/standard-role-types
// → finds id: "srt-ng-admin-uuid"

// Create the standard role scoped to NG-ACME
POST /auth/v1/standard-roles
{
  "standardRoleTypeId": "srt-ng-admin-uuid",
  "resourceIdPath": [
    { "resourceTypeId": "rt-network-group-uuid", "resourceId": "ng-acme-uuid" }
  ]
}
// → { "id": "sr-alice-ng-acme-uuid" }

// Assign it to Alice
POST /auth/v1/standard-role-grants
{
  "identityId": "alice-uuid-1234",
  "standardRoleId": "sr-alice-ng-acme-uuid"
}

Step 3 — Alice logs in

{
  "sub": "alice-uuid-1234",
  "aud": "https://gateway.staging.netfoundry.io/",
  "iss": "NetFoundry",
  "grants-standard": "[{\"id\":\"sr-alice-ng-acme-uuid\",\"v\":1234567}]",
  "grants-public":   "[{\"id\":\"pub-geo-read-uuid\",\"v\":...}, ...]",
  "grants-custom":   "[]",
  "grants-action":   "[]",
  "grants-super":    "[]"
}

Step 4 — Alice calls GET /networks

GET https://gateway.staging.netfoundry.io/core/v2/networks
Authorization: Bearer <Alice's NF JWT>

Step 5 — Alice tries to create an endpoint

POST /core/v2/networks/net-xyz/endpoints
Authorization: Bearer <Alice's NF JWT>
{ "name": "my-laptop" }

Org Admin — What It Covers and What It Does Not

"Org Admin" is not a special system concept. It is simply a StandardRole where the StandardRoleType targets the organization resource type in the io.netfoundry.identity domain with the Admin strategy, scoped to a specific org UUID.

StandardRoleType
  resourceTypeId            = <id of "organization" in io.netfoundry.identity>
  authorizationStrategyName = "Admin"

StandardRole
  standardRoleTypeId = above
  ancestry: resourceId = org-acme-uuid      ← pinned to ACME's org

IdentityStandardRole
  identityId     = alice-uuid
  standardRoleId = above                    ← Alice holds it

What Org Admin Actually Grants

The ActionInclusion rules for the Admin strategy determine exactly what actions Alice gets. The organization resource type is at depth 0 (root), so its children — user-identity, api-account-identity, service-identity, invitation — are all "below" it.

What Org Admin Does NOT Grant — The Two-Domain Split

The two domain trees look like this:

io.netfoundry.identity domain        io.netfoundry.network domain
─────────────────────────────        ──────────────────────────────────
organization  (depth 0)              network-group  (depth 0)
  ├── user-identity  (depth 1)         └── network  (depth 1)
  ├── api-account-identity                    ├── endpoint  (depth 2)
  ├── service-identity                        ├── service
  └── invitation                              └── appwan

      ← Org Admin covers this →            ← NOT covered by Org Admin →

The link between an org and its network-group (the fact that ACME's org owns ACME's network-group) exists only in the Identity Service and Core Service databases — not in the permissions DB. The permissions DB has no structural link between the two domains.

A Full Customer Admin Needs Two Separate Grants

To give Alice full admin over everything ACME-related, you need one grant in each domain:

Grant 1 — covers identity resources:
  IdentityStandardRole
    identityId     = alice-uuid
    standardRoleId → StandardRole(type=OrgAdmin, path=org-acme-uuid)

Grant 2 — covers network resources:
  IdentityStandardRole
    identityId     = alice-uuid
    standardRoleId → StandardRole(type=NetworkGroupAdmin, path=ng-acme-uuid)

Alice's NF JWT after login will carry both in grants-standard:

{
  "sub": "alice-uuid",
  "grants-standard": "[
    {\"id\": \"sr-org-acme-uuid\",  \"v\": 1700001000},
    {\"id\": \"sr-ng-acme-uuid\",   \"v\": 1700001100}
  ]",
  ...
}

When the Identity Service checks "can Alice create a user under org-acme?" it resolves grant 1.
When the Network Service checks "can Alice create a network under ng-acme?" it resolves grant 2.
Each service looks only at actions belonging to its own domain.

Domain Is the Primary Segregation Boundary

Every authorization check matches three things in order: domain code → resource type code → action code. A grant in io.netfoundry.network can never satisfy a check for an io.netfoundry.identity action — they are hard walls.

StandardRole Grant Lifecycle — Who Creates What and When

This section answers the operational question: when a new customer is onboarded, what actually happens in the DB? Who creates the StandardRole rows? What does the NF JWT carry after all that?

Step 1 — StandardRoleType: Already Exists (migration-seeded)

Nothing to do here. StandardRoleTypes are seeded once by Flyway and never change. Before any customer exists, the definition of "Admin on network-group" already lives in the DB.

Step 2 — StandardRole: Created When a Resource Is Provisioned

When ACME's network-group is created, a provisioning service (an internal service identity) calls:

POST /auth/v1/standard-roles
{
  "standardRoleTypeId": "fad425e6-...",   // Network Group Admin
  "path": "io.netfoundry.network:network-group:ng-acme-uuid"
}

The service implementation is idempotent. If a StandardRole of the same type for the same resource already exists (not deleted), it returns the existing one instead of creating a duplicate:

// StandardRoleService.createStandardRole() — abridged
Set<StandardRole> existing = standardRoleRepository
    .selectForUpdate(column("standardRoleTypeId", standardRoleTypeId))
    .stream()
    .filter(sr -> sr.getPath().getLastPathElement()
                              .getResourceId().equals(path.getLastPathElement().getResourceId()))
    .filter(sr -> sr.getDeletedAt() == null)
    .collect(toSet());

if (!existing.isEmpty()) return existing.iterator().next();  // ← return existing, not a new one

return standardRoleRepository.create(...);

Who creates StandardRole instances in production?

Two types of creators appear as the createdBy value on StandardRole rows:

This is why hundreds of StandardRole records all share the same createdBy — every customer provisioned by the Customer Service triggers the same automated call.

Step 3 — IdentityStandardRole: Created When a User Is Granted Access

POST /auth/v1/standard-role-grants
{
  "standardRoleId": "sr-ng-acme-uuid",
  "identityId":     "alice-uuid"
}

This writes one row to IdentityStandardRole. Also idempotent — if Alice already has this grant, the existing one is returned.

Step 4 — NF JWT: What the Token Carries

When Alice calls POST /exchange, AuthorizationController.addDefaultClaims() runs:

standardRoleService.findStandardRoles(null, alice-uuid, null, null)

This joins IdentityStandardRole → StandardRole and returns all non-deleted StandardRole rows Alice has a grant for. Each result becomes a grant reference — just the ID and the updatedAt epoch-seconds as a version fence.

{
  "sub":             "alice-uuid",
  "grants-standard": "[{\"id\":\"sr-ng-acme-uuid\", \"v\":1700001000}]",
  ...
}

The v field is a minimum-version fence: if the cached StandardRole's updatedAt is older than v, the entry must be refreshed before it can be used. This protects against stale cache entries but does not protect against revocation — a revoked grant keeps working until the JWT expires (max 5 minutes).

Summary — What Row Gets Created at Each Stage

How a Created Resource Connects to Alice's Identity

When Alice creates a network net-xyz under ng-acme, zero new rows are written to the permissions DB. There is no row anywhere that says "Alice owns net-xyz". The connection exists across two separate databases and is assembled at check time.

The Two DBs Side by Side

Permissions DB (auth service)           Core/Network Service DB
─────────────────────────────           ──────────────────────────────────
StandardRole                            networks table:
  path = ng-acme-uuid        ←──╮         id           = net-xyz
IdentityStandardRole              │         networkGroupId = ng-acme-uuid  ← parent
  identityId = alice-uuid         │         createdBy     = alice-uuid     ← owner
  standardRoleId → above          │
                                 ╯
              No net-xyz row here at all

What Happens at Check Time

When Alice calls GET /core/v2/networks/net-xyz, the Core service does three things before the auth check fires:

1. Load the resource from Core DB

Network { id: net-xyz, networkGroupId: ng-acme, createdBy: alice-uuid }

2. Build the target path via ResourceResolver.getResourceIdPath()

The Core service's implementation of ResourceResolver walks up through its own DB to construct the full path:

io.netfoundry.network : network-group/ng-acme → network/net-xyz

This path comes entirely from the Core service DB — the permissions DB has no knowledge of net-xyz.

3. Fetch the owner via ResourceResolver.getOwnerIdentityId()

ownerIdentityId = networks.createdBy = alice-uuid    ← from Core DB

4. Authorization.isAuthorized() checks grant path against target path

Alice's grant path:  ng-acme                        (from JWT grants-standard)
Target path:         ng-acme → net-xyz               (built by Core service)

Is ng-acme a prefix of ng-acme → net-xyz?  ✅  → AUTHORIZED

Where Each Piece of Information Lives

NFADMIN — The Root Super-User

An NFADMIN user is a NetFoundry internal identity that holds a SuperUser grant with domainId = NULL. This gives them unrestricted access to every resource across every domain. They are essentially the root administrator of the entire platform.

How to make Alice an NFADMIN user

Via SQL (bootstrap / emergency)

-- Find Alice's identity UUID first
-- SET @identityId = UNHEX('<alice-hex-uuid-without-dashes>');

SET @identityId = UNHEX(REPLACE('alice-uuid-1234', '-', ''));

INSERT INTO SuperUser (id, identityId, domainId) VALUES (
    UNHEX(REPLACE(UUID(), '-', '')),
    @identityId,
    null   -- null = super-user over ALL domains
);

Via REST API (requires an existing super-user to call this)

POST /auth/v1/super-users
Authorization: Bearer <existing super-user's NF JWT>
Content-Type: application/json

{
  "identityId": "alice-uuid-1234",
  "domainId": null
}

What NFADMIN can do

• Create, read, update, delete any resource in any domain
• Grant and revoke any grant type to any identity
• Create organizations, add users to any organization
• Access all networks across all customers
• Manage the authorization model itself (add resource types, actions)

Verifying NFADMIN access in the NF JWT

After Alice logs in with NFADMIN, her NF JWT's grants-super claim will be non-empty:

{
  "grants-super": "[{\"id\":\"su-grant-uuid\",\"v\":1234567890}]",
  "grants-standard": "[]",
  ...
}

When the Auth Service resolves this, Authorization.isAuthorized() short-circuits at the SuperUser check and returns true immediately for any action on any resource.

System Bootstrap — Setting Up NFADMIN from Scratch

Bootstrap is the process of initialising the platform for the very first time — before any SuperUser exists, before any org is created, before any login is possible. Because every API call requires an authorised identity, and no authorised identity exists yet, the entire bootstrap must be done via direct DB inserts.

What Bootstrap Creates

Complete Bootstrap Sequence

INSERT INTO identity.realm (id, label)
VALUES (
    0xb5f8db6b40f44d1686356c48b592d5cd,
    'netfoundry'
);
-- Auth0 tenant URL, client_id, client_secret stored separately
-- in realm config (omitted here for security)

INSERT INTO identity.tenant (id, realmId, label, name, active)
VALUES (
    0x01909a8ea1cb11ef874da29c2afc7246,
    0xb5f8db6b40f44d1686356c48b592d5cd,  -- realm above
    'NFADMIN',
    'NetFoundry Administrative Tenant',
    true
);

INSERT INTO identity.IdentityProvider (id, organizationId, auth0ConnectionId, name, auth0ConnectionType, active)
VALUES (
    0x019ff31ca1cb11ef874da29c2afc7246,
    0x01909a8ea1cb11ef874da29c2afc7246,  -- NFADMIN org
    'google-oauth2',
    'Google Account',
    'Social',
    true
);

INSERT INTO identity.UserIdentity (id, organizationId, firstName, lastName, email, active)
VALUES (
    0x6fa59db2a1cb11ef874da29c2afc7246,
    0x01909a8ea1cb11ef874da29c2afc7246,  -- NFADMIN org
    '',
    'NFADMIN Root User',
    'no-reply@netfoundry.io',            -- placeholder, not a real mailbox
    true
);

-- Find the person's Auth0 sub by decoding their Google login token,
-- or from Auth0 Dashboard → User Management → User → User ID field.

INSERT INTO identity.IdentityMapping (id, userIdentityId, auth0UserId, identityProviderId)
VALUES (
    UNHEX(REPLACE(UUID(), '-', '')),
    0x6fa59db2a1cb11ef874da29c2afc7246,    -- NFADMIN Root User
    'google-oauth2|116549977878305133269',  -- bootstrap person's Google sub
    0x019ff31ca1cb11ef874da29c2afc7246     -- Google identity provider
);

USE permissions;

-- Confirm the identity UUID from the identity service DB first:
-- SELECT HEX(id) FROM identity.UserIdentity WHERE lastName = 'NFADMIN Root User';

SET @identityId = 0x6fa59db2a1cb11ef874da29c2afc7246;
SET @superUserId = UNHEX(REPLACE(UUID(), '-', ''));

INSERT INTO SuperUser (id, identityId, domainId, createdBy)
VALUES (
    @superUserId,
    @identityId,
    NULL,          -- NULL = unrestricted access across ALL domains
    @identityId    -- self-referential for bootstrap
);

-- Verify:
SELECT HEX(id), HEX(identityId), HEX(domainId), createdAt
FROM SuperUser
WHERE identityId = @identityId AND deletedAt IS NULL;

What You Can Do After Bootstrap

Once step 6 is complete, the bootstrap person can log in with their Google account. From that point on, all further setup is done via the API — no more manual DB inserts needed:

Bootstrap Data Flow

NFSUPPORT — Support Staff Roles

NF Support users are NetFoundry employees who need to access customer environments for troubleshooting and operations. Unlike NFADMIN, they do NOT have unrestricted access. Instead they are assigned one of two well-known Custom Roles:

How to make Alice an NFSUPPORT (Intervention) user

Because the Custom Role already exists with a static ID, all you need to do is grant it to Alice:

POST /auth/v1/custom-role-grants
Authorization: Bearer <NF JWT of an admin who can grant custom roles>

{
  "identityId": "alice-uuid-1234",
  "customRoleId": "97315ed6-2fc7-4a40-b7ea-abe53cc6a188",
  "resourceIdPath": []   // empty = grant applies to ALL resources globally
}

Alice's next login will produce an NF JWT where grants-custom contains a reference to this custom role. Every downstream service that checks her authorization will resolve the role and grant her the support-level permissions.

Key difference: NFADMIN vs NFSUPPORT

Adding new actions to NFSUPPORT via migration

When a new resource type or custom action is added to the platform, it must be explicitly added to the NFSUPPORT custom roles. This is done via a Flyway migration:

-- V2.XXX.0__grant-new-action-to-nfsupport.sql

SET @interventionCustomRoleId = X'97315ed62fc74a40b7eaabe53cc6a188';
SET @domainId = (SELECT id FROM Domain WHERE code = 'io.netfoundry.network');

INSERT IGNORE INTO CustomRoleAction (id, customRoleId, resourceActionId)
SELECT UUID(), @interventionCustomRoleId, RA.id
FROM ResourceAction RA JOIN ResourceType RT on RA.resourceTypeId = RT.id
WHERE RA.code = 'update-new-action'
  AND RT.code = 'your-new-resource-type'
  AND RT.domainId = @domainId;

Owner-Identity Dynamic Grants

When Alice has a grant scoped to a resource (e.g., "Network Admin of net-xyz"), and she tries to act on something below that resource (e.g., an endpoint under it), the auth system does not simply check grant path prefix. It also checks whether Alice created the resource she is trying to act on. This is the owner-identity pattern.

Where the Owner Is Stored

When Alice creates an endpoint, the Core service stores createdBy = alice-uuid in its own DB. The permissions DB has no record of this. At check time, the Core service fetches it via ResourceResolver.getOwnerIdentityId() and passes it to the auth check as a Supplier<UUID>.

Authorization.isAuthorized(
    alice-uuid,                                      // who is asking
    authorizationSet,                                // her grants from JWT
    "io.netfoundry.network", "endpoint", "update",  // what she wants to do
    targetPath,                                      // path to the endpoint
    () -> endpointRepository.findOwnerIdentityId(endpointId)  // ← owner supplier
);

The Delta-Depth Rule — When Owner Check Fires

The logic in Authorization.isOwnerIdentityAuthorized() computes the depth difference between the action's resource type and the grant's resource type:

deltaDepth = actionResourceType.getDepth() - grantPath.getLastPathElement().getResourceType().getDepth()

// positive  →  action is BELOW the grant level  →  owner check applies
// zero      →  action is AT the grant level      →  no owner check, just authorized
// negative  →  action is ABOVE the grant level   →  no owner check, just authorized

The Decision Once Owner Check Fires

// from Authorization.isOwnerIdentityAuthorized()
if (deltaDepth <= 0) {
    return true;  // at or above — owner identity irrelevant
}
// below: permit create, enforce owner match for everything else
if (action.getCode().equals("create") || action.getCode().startsWith("create-")) {
    return true;  // can always create under a resource in your grant scope
}
return identityId.equals(ownerIdentityIdOfTargetResource);
    // alice-uuid == endpoint.createdBy  ?

Full Token Lifecycle

Token renewal

NF JWT expires every 5 minutes
      ↓
Console UI detects 401 response
      ↓
Calls POST /exchange again with same Auth0 JWT (still valid for 24h)
      ↓
Gets fresh NF JWT
      ↓
Retries original request

Auth Service's own token (inter-service)

Auth Service starts up
      ↓
InterServiceTokenProvider calls POST Auth0 /oauth/token
with client_credentials (clientId + clientSecret)
      ↓
Gets Auth0 JWT for the service's own identity
Validates it, extracts service-identity UUID
      ↓
Scheduled refresh 60 minutes before expiry (24h token)
      ↓
When calling other services: POST /exchange?audience=<target>
Gets NF JWT scoped to that specific target service (aud: target URL)

NF JWT — What's Inside

The NF JWT carries five custom claims, each a JSON-serialized array of {id, v} grant references:

{
  // Standard JWT fields
  "sub":  "alice-uuid-1234",                // identity UUID
  "iss":  "NetFoundry",                      // always this
  "aud":  "https://gateway.staging.netfoundry.io/",
  "iat":  1779173775,
  "exp":  1779173775 + 300,                  // 5 minutes TTL

  // NetFoundry grant claims (compact references, NOT full data)
  "grants-public":   "[{\"id\":\"pub-uuid\",\"v\":1234}]",
  "grants-super":    "[]",                   // empty if not a superuser
  "grants-action":   "[]",
  "grants-custom":   "[]",
  "grants-standard": "[{\"id\":\"sr-uuid\",\"v\":9876}]"
}

The v field is the grant's updatedAt epoch second (version). When a downstream service resolves grants, it uses this to detect if its local cache is stale — if the cache entry's version is older than v, it fetches fresh data.

Complete Login Flow — Prashant Logs into NFADMIN

This is the real end-to-end login flow traced from a live session. It covers every network call the browser makes, what happens server-side (invisible to the browser), and exactly how a Google Workspace account ends up with full platform access.

Phase 1 — UI Initiates Login

SELECT * FROM identity.tenant WHERE label = 'NFADMIN'
→ id:    01909a8e-a1cb-11ef-874d-a29c2afc7246
→ name:  NetFoundry Administrative Tenant

SELECT * FROM identity.realm WHERE label = 'netfoundry'
→ id:    b5f8db6b-40f4-4d16-8635-6c48b592d5cd
→ auth0: netfoundry-sandbox.auth0.com

Request:
{
  "tenantLabel": "NFADMIN",
  "intermediateReturnUrl": "http://localhost:4200/login",
  "realm": "netfoundry"
}

State JWT payload (decoded):
{
  "iss":  "https://gateway.sandbox.netfoundry.io/identity/v1",
  "aud":  "https://netfoundry-sandbox.auth0.com/",
  "flow": "login",
  "tenantLabel": "NFADMIN",
  "auth0ConnectionIds": ["google-oauth2"],
  "redirectUrl": "http://localhost:4200/login",
  "exp": iat + 900   ← 15 minutes only
}

Phase 2 — Auth0 PKCE Authentication

State (decoded from MessagePack binary):
{
  "h":   "tQCrBhpi8ipo-y7lWksxANUFk5-V92US",   ← session hash (CSRF)
  "n":   "login",
  "tid": "MNi8kowGiRDmov6apBDOOWgWUJyd8NFi",   ← Auth0 tenant ID
  "cid": "6WXzPe5Zu3Z0VjJDbwZcsZ71JeGRDJOp"    ← Auth0 client ID
}

Request:
  grant_type:    authorization_code
  code:          sLUoyA1b6in...          ← one-time code from Auth0 callback
  code_verifier: rQusde128ZW...          ← PKCE secret (proves same client started login)
  client_id:     6WXzPe5Zu3Z0Vj...
  redirect_uri:  http://nfadmin.localhost:4200/callback

Response — access_token (24h) payload:
{
  "iss": "https://netfoundry-sandbox.auth0.com/",
  "sub": "google-oauth2|116549977878305133269",   ← Prashant's Google identity
  "aud": ["http://localhost:8080/", "...userinfo"],
  "https://netfoundry.io/tenant/label":       "NFADMIN",    ← injected by Auth0 Rule
  "https://netfoundry.io/auth0/connectionId": "google-oauth2",
  "exp": iat + 86400   ← 24 hours
}

Response — id_token (10h) payload:
{
  "sub":          "google-oauth2|116549977878305133269",
  "email":        "prashant.savadi@netfoundry.io",
  "given_name":   "Prashant",
  "family_name":  "Savadi"
}

Phase 3 — Identity Resolution

SELECT ui.* FROM identity.UserIdentity ui
JOIN identity.IdentityMapping im ON im.userIdentityId = ui.id
WHERE im.auth0UserId = 'google-oauth2|116549977878305133269'

Response:
{
  "id":       "6fa59db2-a1cb-11ef-874d-a29c2afc7246",   ← Prashant's identityId
  "lastName": "NFADMIN Root User",
  "email":    "no-reply@netfoundry.io",
  "identityMappings": [{
    "auth0UserId": "google-oauth2|116549977878305133269"  ← linked to Prashant's Google
  }]
}

Response:
{
  "id":    "01909a8e-a1cb-11ef-874d-a29c2afc7246",   ← NFADMIN org UUID
  "name":  "NetFoundry Administrative Tenant",
  "label": "NFADMIN",
  "identityProviders": [{ "auth0ConnectionId": "google-oauth2" }]
}

POST http://localhost:8095/exchange
Authorization: Bearer <Auth0 access_token>

SELECT * FROM SuperUser
WHERE identityId = 0x6fa59db2a1cb11ef874da29c2afc7246
  AND deletedAt IS NULL
→ row found: domainId = NULL   ← full platform SuperUser

{
  "sub":           "6fa59db2-a1cb-11ef-874d-a29c2afc7246",   ← UUID now, not Google sub
  "iss":           "NetFoundry",
  "aud":           "http://localhost:8080/",
  "iat":           <now>,
  "exp":           <now + 300>,
  "grants-super":    "[{\"id\":\"<superUserId>\",\"v\":<epoch>}]",
  "grants-public":   "[...]",
  "grants-standard": "[]",
  "grants-custom":   "[]",
  "grants-action":   "[]"
}

Phase 4 — Authorization Resolution (UI Rendering)

PublicGrants   → all public grants (geo-regions, data-centers, etc.)
SuperUser      → domainId=NULL found → full platform access
StandardRoles  → none (SuperUser covers everything)
CustomRoles    → none
ActionGrants   → none

Phase 5 — Downstream API Calls via Gateway

GET http://localhost:8080/core/v3/networks
Authorization: Bearer <Auth0 token>   ← what browser sends to gateway

Gateway → POST /exchange → NF JWT
Gateway → Core Service
  GET /core/v3/networks
  Authorization: Bearer <NF JWT>   ← NF JWT, not Auth0 token

Complete Flow Summary

Why Prashant Has Full Access — The Chain

prashant.savadi@netfoundry.io  (Google Workspace)
    │
    │  Auth0 sub: google-oauth2|116549977878305133269
    │                  ↓  identity.IdentityMapping  (manually inserted during bootstrap)
    │
    ├── UserIdentity: 6fa59db2-a1cb-11ef-874d-a29c2afc7246
    │       lastName: "NFADMIN Root User"   ← system identity, email = no-reply@netfoundry.io
    │
    │         ↓  permissions.SuperUser  (inserted via insert-superuser.sql utility)
    │
    └── SuperUser: identityId = 6fa59db2..., domainId = NULL
            → unrestricted access to ALL domains, ALL resources, ALL actions

How the Bootstrap Was Done (Manual DB Inserts)

-- Create the NFADMIN Root User system identity
INSERT INTO identity.UserIdentity (id, organizationId, lastName, email, active)
VALUES (
    0x6fa59db2a1cb11ef874da29c2afc7246,
    0x01909a8ea1cb11ef874da29c2afc7246,  -- NFADMIN org
    'NFADMIN Root User',
    'no-reply@netfoundry.io',            -- placeholder, not a real mailbox
    true
);

-- Link Prashant's Google account to this identity
INSERT INTO identity.IdentityMapping (id, userIdentityId, auth0UserId, identityProviderId)
VALUES (
    0x6fba6580a1cb11ef874da29c2afc7246,
    0x6fa59db2a1cb11ef874da29c2afc7246,   -- NFADMIN Root User above
    'google-oauth2|116549977878305133269', -- Prashant's Google sub from Auth0
    0x019ff31ca1cb11ef874da29c2afc7246    -- Google identity provider record
);

-- From: src/main/resources/database/util/insert-superuser.sql
-- First find the identity UUID:
-- SELECT HEX(id) FROM identity.UserIdentity WHERE lastName = 'NFADMIN Root User';

SET @identityId = 0x6fa59db2a1cb11ef874da29c2afc7246;

INSERT INTO SuperUser (id, identityId, domainId, createdBy)
VALUES (
    UNHEX(REPLACE(UUID(), '-', '')),
    @identityId,
    NULL,          -- NULL = super-user over ALL domains
    @identityId    -- created by itself (bootstrap)
);

How to Add a New Resource Type

Adding a new resource type means any service can now have authorization checks for that resource. Here is the complete process:

USE permissions;

-- 1. Find the parent domain and parent resource type
SET @domainId = (SELECT id FROM Domain WHERE code = 'io.netfoundry.network');
SET @parentId = (SELECT id FROM ResourceType WHERE code = 'network' AND domainId = @domainId);

-- 2. Create the new resource type
INSERT INTO ResourceType (id, domainId, name, code, parentId) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @domainId, 'My Resource', 'my-resource', @parentId);

SET @myResourceTypeId = (SELECT id FROM ResourceType WHERE code = 'my-resource' AND domainId = @domainId);

-- 3. Create standard CRUD actions
INSERT INTO ResourceAction (id, resourceTypeId, name, code) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @myResourceTypeId, 'Create', 'create'),
(UNHEX(REPLACE(UUID(),'-','')), @myResourceTypeId, 'Read',   'read'),
(UNHEX(REPLACE(UUID(),'-','')), @myResourceTypeId, 'Update', 'update'),
(UNHEX(REPLACE(UUID(),'-','')), @myResourceTypeId, 'Delete', 'delete');

-- 4. Create action inclusions so Standard Roles work correctly
INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow)
SELECT UNHEX(REPLACE(UUID(),'-','')), id, 'Read-Only', 1, 1, 1
FROM ResourceAction WHERE resourceTypeId = @myResourceTypeId AND code = 'read';

INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow)
SELECT UNHEX(REPLACE(UUID(),'-','')), id, 'Admin', 1, 1, 1
FROM ResourceAction WHERE resourceTypeId = @myResourceTypeId AND code = 'read';

INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow)
SELECT UNHEX(REPLACE(UUID(),'-','')), id, 'Admin', 0, 0, 1
FROM ResourceAction WHERE resourceTypeId = @myResourceTypeId AND code = 'create';

INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow)
SELECT UNHEX(REPLACE(UUID(),'-','')), id, 'Admin', 0, 1, 1
FROM ResourceAction WHERE resourceTypeId = @myResourceTypeId AND code = 'update';

INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow)
SELECT UNHEX(REPLACE(UUID(),'-','')), id, 'Admin', 0, 0, 1
FROM ResourceAction WHERE resourceTypeId = @myResourceTypeId AND code = 'delete';

-- In a follow-up migration: V2.<next+1>.0__grant-my-resource-to-nfsupport.sql
SET @interventionCustomRoleId = X'97315ed62fc74a40b7eaabe53cc6a188';
INSERT IGNORE INTO CustomRoleAction (id, customRoleId, resourceActionId)
SELECT UUID(), @interventionCustomRoleId, RA.id
FROM ResourceAction RA JOIN ResourceType RT on RA.resourceTypeId = RT.id
WHERE RA.code IN ('read', 'create', 'update', 'delete')
  AND RT.code = 'my-resource' AND RT.domainId = @domainId;

@PostMapping("/my-resources")
public MyResource create(
    @AuthCreate(on = MyResource.class)
    @RequestParam UUID networkId
) {
    // If we reach here, the caller is authorized
}

How to Add a Custom Action to an Existing Resource Type

-- V2.XXX.0__add-network-publish-action.sql
USE permissions;

SET @domainId = (SELECT id FROM Domain WHERE code = 'io.netfoundry.network');
SET @networkTypeId = (SELECT id FROM ResourceType WHERE code = 'network' AND domainId = @domainId);

-- Create the new custom action
INSERT INTO ResourceAction (id, resourceTypeId, name, code) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @networkTypeId, 'Publish', 'publish');

SET @publishActionId = (SELECT id FROM ResourceAction WHERE code = 'publish' AND resourceTypeId = @networkTypeId);

-- Decide: should Admin strategy include this?  Yes, at the network level and below.
INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @publishActionId, 'Admin', 0, 1, 0);

-- Grant it to NFSUPPORT intervention as well
SET @interventionCustomRoleId = X'97315ed62fc74a40b7eaabe53cc6a188';
INSERT IGNORE INTO CustomRoleAction (id, customRoleId, resourceActionId) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @interventionCustomRoleId, @publishActionId);

How to Create a New Standard Role Type

Standard Role Types are templates. Once created, instances can be granted to any identity over any resource path of the matching resource type.

-- V2.XXX.0__add-network-contributor-standard-role-type.sql
USE permissions;

SET @domainId = (SELECT id FROM Domain WHERE code = 'io.netfoundry.network');
SET @networkTypeId = (SELECT id FROM ResourceType WHERE code = 'network' AND domainId = @domainId);

-- Create the StandardRoleType
INSERT INTO StandardRoleType (id, resourceTypeId, authorizationStrategyName) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @networkTypeId, 'Contributor');

-- Now create ActionInclusions for the 'Contributor' strategy
-- Contributor can read and update, but not create or delete
SET @readActionId = (SELECT id FROM ResourceAction WHERE code = 'read' AND resourceTypeId = @networkTypeId);
SET @updateActionId = (SELECT id FROM ResourceAction WHERE code = 'update' AND resourceTypeId = @networkTypeId);

INSERT INTO ActionInclusion (id, resourceActionId, authorizationStrategyName,
    includeWhenAbove, includeWhenAt, includeWhenBelow) VALUES
(UNHEX(REPLACE(UUID(),'-','')), @readActionId,   'Contributor', 1, 1, 1),
(UNHEX(REPLACE(UUID(),'-','')), @updateActionId, 'Contributor', 0, 1, 1);

After this migration runs, you can grant this role type to any identity via the REST API:

// Find the new StandardRoleType
GET /auth/v1/standard-role-types
// → { "id": "srt-contributor-uuid", "authorizationStrategyName": "Contributor", ... }

// Create an instance scoped to a specific network
POST /auth/v1/standard-roles
{
  "standardRoleTypeId": "srt-contributor-uuid",
  "resourceIdPath": [
    { "resourceTypeId": "rt-ng-uuid", "resourceId": "ng-abc-uuid" },
    { "resourceTypeId": "rt-network-uuid", "resourceId": "net-xyz-uuid" }
  ]
}

// Grant to Alice
POST /auth/v1/standard-role-grants
{ "identityId": "alice-uuid", "standardRoleId": "sr-new-uuid" }

How to Create a Custom Role

Custom Roles are best for service accounts and support staff who need a specific, non-standard set of permissions that doesn't map to a neat "Admin" or "Read-Only" strategy.

POST /auth/v1/custom-roles
{ "name": "Billing Read-Only" }
// → { "id": "cr-billing-ro-uuid" }

// First, find the action UUIDs you need
GET /auth/v1/resource-actions?resourceTypeCode=billing-account&code=read
// → { "id": "ra-billing-read-uuid" }

POST /auth/v1/custom-role-actions
{
  "customRoleId": "cr-billing-ro-uuid",
  "resourceActionId": "ra-billing-read-uuid",
  "resourceIdPath": []   // empty = applies to all billing accounts
}

POST /auth/v1/custom-role-grants
{
  "identityId": "billing-service-identity-uuid",
  "customRoleId": "cr-billing-ro-uuid",
  "resourceIdPath": []   // no path scoping = global
}

Complete Checklist: Granting a New User Access

Here is the complete checklist to configure a new user from zero to having meaningful API access:

GET /auth/v1/authorizations?identityId=alice-uuid-1234
Authorization: Bearer <any valid NF JWT>

// Response:
{
  "identityId": "alice-uuid-1234",
  "grants": {
    "io.netfoundry.network/network-group/read": [
      "network-group/ng-acme-uuid"
    ],
    "io.netfoundry.network/network/read": [
      "network-group/ng-acme-uuid"
    ],
    "io.netfoundry.network/endpoint/create": [
      "network-group/ng-acme-uuid"
    ],
    ...
  }
}

API Reference Summary

Base URL: https://gateway.staging.netfoundry.io/auth/v1/

All endpoints require Authorization: Bearer <NF JWT>.

Database Schema Overview

The authorization service uses a MySQL database named permissions. All tables use binary(16) UUIDs as primary keys and carry createdAt, updatedAt, and deletedAt columns — the service uses soft-deletes exclusively. A non-null deletedAt means the row is logically deleted but physically retained for history.

The schema falls into four conceptual groups:

DB Design — Four Conceptual Layers

The permissions schema is best understood as four stacked layers. Each layer depends on the one above it, and together they answer a single question: "Does identity X have permission to perform action Y on resource Z?"

How a "Network Admin on NG-1" is stored across all four layers

What the NF JWT carries from these layers

When Alice calls POST /exchange, the Auth Service walks Layer 3 (her grant assignments), collects each grant's ID and its updatedAt timestamp, and embeds them as compact references in the NF JWT. No Layer 1, 2, or 4 data enters the token — only IDs and versions.

{
  "sub": "alice-uuid",
  "grants-standard": "[{\"id\":\"sr-ng1-admin\",\"lm\":1692000000000}]",  // ← Layer 3 ID only
  "grants-public":   "[{\"id\":\"pg-geo-read\",\"lm\":...}]",
  "grants-super":    "[]",
  "grants-action":   "[]",
  "grants-custom":   "[]"
}

How downstream services reconstruct full permissions from those IDs

Metadata Tables

These tables form the authoritative catalog of everything that can be authorized. They are populated once by Flyway migrations and act as read-only reference data at runtime.

Domain

ResourceType

geo-region          (depth 0, root, parentId = null)
data-center         (depth 0, root, parentId = null)
network-group       (depth 0, root, parentId = null)
  ├── network       (depth 1, parentId = network-group)
  │     ├── endpoint     (depth 2)
  │     ├── appwan       (depth 2)
  │     ├── service      (depth 2)
  │     └── edge-router  (depth 2)
  ├── azure-subscription (depth 1)
  └── netflow-collector  (depth 1)

ResourceAction

ActionInclusion

StandardRoleType

Grant Tables

These tables are the runtime permission assignment data. A row in a grant table means "this identity has this permission".

SuperUser

INSERT INTO SuperUser (id, identityId, domainId)
VALUES (UNHEX(REPLACE(UUID(),'-','')), UNHEX('<your-identity-uuid-no-dashes>'), NULL);

PublicGrant & PublicGrantResourceAncestry

IdentityResourceAction & IdentityResourceActionResourceAncestry

-- The Identity Service's identity UUID is a fixed UUID baked into the DB
INSERT INTO IdentityResourceAction (id, identityId, resourceActionId)
VALUES (UNHEX(REPLACE(UUID(),'-','')),
        UNHEX('<identity-service-sid-uuid>'),
        (SELECT id FROM ResourceAction RA
           JOIN ResourceType RT ON RA.resourceTypeId = RT.id
         WHERE RT.code = 'user-identity' AND RA.code = 'create'));
-- No ancestry rows = global scope (all orgs)

CustomRole, CustomRoleAction & CustomRoleActionResourceAncestry

StandardRole, StandardRoleResourceAncestry & IdentityStandardRole

Ancestry (Path) Tables

Every grant that can be scoped to a resource path has a companion ancestry table. The pattern is consistent: one ancestry table per grant type (plus one for custom role actions).

Ancestry Row Structure

Entity Relationship Diagram

The following diagram shows all tables and their foreign key relationships. Ancestry tables (right column) are the path-scoping companions to their parent grant tables.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                         METADATA / DEFINITION LAYER                             │
│                                                                                 │
│  Domain ──────────────────────────────────────────────────────────────────────  │
│    │ id, name, code                                                              │
│    │                                                                             │
│    ▼                                                                             │
│  ResourceType ──────────────────────────────────────────────────────────────    │
│    │ id, domainId→Domain, code, parentId→ResourceType(self)                     │
│    │                                                                             │
│    ├──────────────────────┐                        ┌──────────────────────────  │
│    ▼                      ▼                        ▼                            │
│  ResourceAction      StandardRoleType          ActionInclusion                  │
│    id, resourceTypeId    id, resourceTypeId        id, resourceActionId          │
│    code (create/read/    authorizationStrategy     authorizationStrategy         │
│    update/delete/…)      Name (Admin/Read-Only/    Name, includeWhenAbove/       │
│                          Contributor)              At/Below                      │
└─────────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              GRANT LAYER                                        │
│                                                                                 │
│  SuperUser                                                                      │
│    id, identityId, domainId→Domain(nullable)                                    │
│                                                                                 │
│  PublicGrant ──────────────────────────────── PublicGrantResourceAncestry       │
│    id, resourceActionId→RA, isAnonymous          id, publicGrantId, childAncestry│
│                                                  Id(self), resourceTypeId,       │
│                                                  resourceId                      │
│                                                                                 │
│  IdentityResourceAction ───────────────────── IdentityResourceAction            │
│    id, identityId, resourceActionId→RA           ResourceAncestry               │
│                                                  id, identityResourceActionId,   │
│                                                  childAncestryId(self),          │
│                                                  resourceTypeId, resourceId      │
│                                                                                 │
│  CustomRole                                                                     │
│    id, name                                                                     │
│    ▼                                                                            │
│  CustomRoleAction ──────────────────────────── CustomRoleAction                 │
│    id, customRoleId→CR, resourceActionId→RA        ResourceAncestry             │
│                                                   id, customRoleActionId,       │
│                                                   childAncestryId(self),        │
│                                                   resourceTypeId, resourceId    │
│    ▼                                                                            │
│  IdentityCustomRole                                                             │
│    id, identityId, customRoleId→CustomRole                                      │
│    UNIQUE(identityId, customRoleId)                                             │
│                                                                                 │
│  StandardRoleType (from metadata layer above)                                   │
│    ▼                                                                            │
│  StandardRole ─────────────────────────────── StandardRoleResourceAncestry      │
│    id, standardRoleTypeId→SRT                    id, standardRoleId, childAnces- │
│                                                  tryId(self), resourceTypeId,   │
│                                                  resourceId                      │
│    ▼                                                                            │
│  IdentityStandardRole                                                           │
│    id, identityId, standardRoleId→StandardRole                                  │
│    UNIQUE(identityId, standardRoleId)                                           │
└─────────────────────────────────────────────────────────────────────────────────┘

Data Flow Summary

When an identity is granted access the data flows through these tables in sequence:

How the Authorization Check Actually Works

The "authorization hook" is the mechanism that connects a JWT in the HTTP Authorization header to a yes/no decision inside every downstream service controller. Understanding this mechanism answers the question: "How does having a row in the database translate to Alice being allowed to call the API?"

The hook operates in three phases:

Human User Flow (Browser / Console UI)

A human user — Alice — logs in through the Console UI (a browser-based SPA). Here is the complete path from login to authorized API call:

{
  "sub": "google-oauth2|116549...",          // Auth0 subject (NOT a UUID)
  "aud": "https://gateway.staging.netfoundry.io/",
  "exp": (now + 86400),                       // 24-hour lifetime
  "https://netfoundry.io/service-identity/id": "alice-uuid-1234"  // NF UUID, injected by Auth0 Action
}

{
  "sub": "alice-uuid-1234",
  "aud": "https://gateway.staging.netfoundry.io/",
  "iss": "NetFoundry",
  "exp": (now + 300),
  "grants-public":   [{"id":"pg-uuid","lm":1},…],
  "grants-super":    [],
  "grants-action":   [],
  "grants-custom":   [],
  "grants-standard": [{"id":"sr-uuid","lm":1692000000000}]
}

@GetMapping("/{id}")
public Network getNetwork(
    @AuthRead(on = Network.class) @PathVariable UUID id
) { ... }

API Account (Machine-to-Human) Flow

An API Account is a non-human identity (an Auth0 Machine-to-Machine application). It is used by automation scripts, CI/CD pipelines, or third-party integrations that call the NetFoundry API programmatically.

POST https://netfoundry-sandbox.auth0.com/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "audience": "https://gateway.staging.netfoundry.io/"
}
→ { "access_token": "<Auth0 JWT>", "expires_in": 86400 }

-- Example: Grant API Account a Read-Only role on a network group
POST /auth/v1/standard-roles
{
  "standardRoleTypeId": "<SRT UUID for network-group/Read-Only>",
  "resourceIdPath": [
    { "resourceTypeId": "<network-group type UUID>", "resourceId": "NG-1-uuid" }
  ]
}
→ { "id": "sr-new-uuid" }

POST /auth/v1/standard-role-grants
{
  "identityId": "api-account-identity-uuid",
  "standardRoleId": "sr-new-uuid"
}

Service-to-Service (Internal Platform) Flow

Internal NetFoundry services (Core Service, Identity Service, Edge Router Service, etc.) also call each other's APIs. They use a different pattern: the InterServiceTokenProvider.

{
  "sub": "core-service-identity-uuid",
  "aud": "https://identity.staging.netfoundry.io/",  // the TARGET service
  "iss": "NetFoundry",
  "exp": (now + 300)
}

The @Auth Annotations — How Downstream Services Enforce Authorization

The client jar (authorization-*-client.jar) ships a set of Jakarta Bean Validation annotations that downstream services add to their Spring MVC controller methods. These annotations are the hook — they are where the yes/no decision happens.

Available Annotations

How They Work

Each annotation is a @Constraint backed by multiple ConstraintValidator implementations (one for each annotated value type: UUID, Supplier<UUID>, WhereClause, Predicate). When Spring MVC processes the controller method parameters, Jakarta Validation is invoked — which triggers the validator.

The validator calls AuthorizationContext.getContext() to obtain the thread-local context, then calls context.isAuthorized(...). If the check fails, the validator returns false from isValid(), which causes Spring to throw a ConstraintViolationException, which is caught by AuthExceptionAdvice and translated to a 403 Forbidden.

Usage Examples

@GetMapping("/networks/{id}")
public Network getNetwork(
    @AuthRead(on = Network.class) @PathVariable UUID id
) {
    return networkService.findById(id);
}

@PostMapping("/networks/{networkId}/endpoints")
public Endpoint createEndpoint(
    @AuthCreate(on = Endpoint.class) @PathVariable UUID networkId,
    @RequestBody EndpointRequest request
) {
    return endpointService.create(networkId, request);
}

@PostMapping("/edge-routers/{id}/heal")
public void healEdgeRouter(
    @AuthAction(on = EdgeRouter.class, action = "update-heal") @PathVariable UUID id
) {
    edgeRouterService.heal(id);
}

The AuthorizationContext + @Auth Annotation Flow — Complete Picture

HTTP Request with Authorization: Bearer <NF JWT>
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  HandlerInterceptor (preHandle)                          │
│  → checkVersions() on all InMemoryRepositories           │
│  → if DB changed, invalidate in-memory cache             │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  Spring MVC DispatcherServlet                            │
│  → routes to controller method                           │
│  → Jakarta Bean Validation triggered on @Auth* params    │
└─────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  AuthIdValidators.AuthReadValidator.isValid(UUID id, …)  │
│  → AuthorizationContext.getContext()                     │
│     → reads Authorization header (once per request)     │
│     → JwtConsumer.processToClaims()                      │
│     → deserializes 5 grant claims → Map<UUID,Long>       │
│  → context.isAuthorized(domain, resourceType, action,    │
│       targetPath, ownerSupplier)                         │
│     → if authorizationSet is null: buildAuthorizationSet()│
│        → for each grant ID in token claims:              │
│          → resolve from in-memory repository             │
│          → AuthorizationSetBuilder.with*Grant()          │
│          → inserts (domain→type→action→grantId→paths)    │
│     → Authorization.isAuthorized(...)                    │
│        → getAuthorizingGrantPaths()                      │
│        → grantPaths.subsetIncludes(targetPath)           │
│        → check owner-dynamic if needed                   │
└─────────────────────────────────────────────────────────┘
         │
    ┌────┴────┐
   true     false
    │         │
    ▼         ▼
  proceed   ConstraintViolationException
            → AuthExceptionAdvice
            → 403 Forbidden

Customer Onboarding Setup

Giving a new customer (tenant) their first admin user requires two distinct layers of configuration. Layer 1 is platform-wide and is done once via Flyway migrations. Layer 2 is per-customer and is driven via REST API calls (typically by the provisioning service).

Layer 1 — Platform-Wide Prerequisites (Flyway Migrations)

These objects exist before any customer is created. They define the permission grammar.

Layer 2 — Per-Customer Setup Steps (REST API)

Each of these steps is triggered for every new customer. The provisioning service calls the Auth Service API.

POST /standard-roles
{
  "standardRoleTypeId": "<org-admin-srt-id>",
  "path": "nf.id:org/<acme-org-uuid>"
}

POST /standard-role-grants
{
  "standardRoleId": "<acme-org-admin-sr-id>",
  "identityId": "<alice-identity-uuid>"
}

Alice's Complete DB Data Flow

This walkthrough shows exactly which rows are written to which tables when Alice is onboarded as the Organization Admin of Acme Corp, which owns the Dev Network Group. All UUIDs are shortened for readability; real rows use full v4 UUIDs.

Phase 0 — Platform Tables (Already Exist)

These rows were inserted by Flyway migrations, not per-customer API calls.

domain

resource_type

standard_role_type

Phase 1 — Create Org-Level StandardRoles for Acme

Provisioner calls POST /standard-roles twice — once for Admin, once for Read-Only.

standard_role (new rows)

standard_role_resource_ancestry (new rows)

The Org-Admin SR's path is a single element: [rt-org / acme-0001]. The ancestry service inserts from leaf (index 1) to root (index 0), but a single-element path has only one row with child_ancestry_id = NULL.

At startup the ResourceAncestryService.getAll() call reads these rows and reconstructs the path. The StandardRole bean then carries: sr-oa-acme.path = [organization/acme-0001].

Phase 2 — Create Network-Group-Level StandardRoles for "Dev NG"

Same pattern, but the path has two elements: [rt-ng / devng-001] (NG depth=0, so path is 1 element).

standard_role (new rows)

standard_role_resource_ancestry (new rows)

Phase 3 — Create Auth Standard Roles (Delegation Wrappers)

For each SR created in phases 1-2, we create two Auth SRs (Admin + Read-Only) whose path is just [standard-role / <wrapped-sr-id>]. Only the Admin wrapper for sr-oa-acme is shown here for brevity.

standard_role (new rows)

standard_role_resource_ancestry (new rows)

Phase 4 — Grant Alice the Org Admin Role

Provisioner calls POST /standard-role-grants.

identity_standard_role (new row)

This single row is the activation event. Everything before this was structural scaffolding; this row is what gives Alice her permissions.

Phase 5 — Alice Logs In: JWT Construction

Alice calls POST /exchange with her Auth0 token. The auth service runs addDefaultClaims():

{
  "sub": "alice-0001",
  "grants-standard": [{ "id": "isr-alice-1", "lastModified": 1716400000000 }],
  "grants-public":   [ /* platform-wide PublicGrants */ ],
  "grants-action":   [],
  "grants-custom":   [],
  "grants-super":    [],
  "exp": 1716400300
}

Phase 6 — Alice Accesses a Resource: Authorization Check

Alice sends a GET /networks/net-xyz request to the Network Service. The @AuthRead(on = Network.class) annotation fires.

Why Each Step Exists — Q&A

Each onboarding step exists for a specific reason. This Q&A walks through the design rationale.

End-to-End: DB Row → NF JWT → Authorization Decision

This section answers the question: "How does a row in IdentityStandardRole translate to Core Management Service (or any MOP service) saying YES or NO to an API call?"

There are two distinct phases separated by the POST /exchange boundary:

Phase A — Inside the Auth Service at POST /exchange

POST /exchange  (caller presents Auth0 JWT)
       │
       ▼
AuthorizationLogic.requestJwt()
  1. Validate Auth0 JWT → extract identityId from custom claim
  2. Load IdentityStandardRole  rows for identityId   →  [{ standardRoleId, updatedAt }]
  3. Load IdentityCustomRole    rows for identityId   →  [{ customRoleId, updatedAt }]
  4. Load IdentityResourceAction rows for identityId  →  [{ actionGrantId, updatedAt }]
  5. Load SuperUser              rows for identityId   →  [{ superUserId, updatedAt }]
  6. Load PublicGrant            rows (global, same for all) → [{ pgId, updatedAt }]
       │
       ▼
Build JwtClaims:
  "grants-standard": "[{id: sr-uuid, lm: 1692000000000}, ...]"
  "grants-custom":   "[{id: cr-uuid, lm: ...}, ...]"
  "grants-action":   "[{id: ira-uuid, lm: ...}, ...]"
  "grants-super":    "[{id: su-uuid, lm: ...}, ...]"  ← empty if not superuser
  "grants-public":   "[{id: pg-uuid, lm: ...}, ...]"
       │
       ▼
Sign with RSA private key (from Redis JwksService)
Return NF JWT  (exp = now + 300 seconds)

Phase B — Inside Every Downstream Service (Core Mgmt, Customer Mgmt, etc.)

Incoming HTTP request
  Authorization: Bearer <NF JWT>
       │
       ▼
① AuthorizationContext.getContext()   [thread-local, per-request]
  • Parses NF JWT using Jose4j JwtConsumer
  • Validates RSA signature against /auth/jwks (cached public key)
  • Deserializes 5 grant claims into Map<UUID grantId, Long version>
  • No DB queries yet — just parse + validate

       │
       ▼ (lazy, on first access)
② AuthorizationSetBuilder.build()     [in-memory only]
  For each grantId in grants-standard:
    → Look up StandardRole in InMemoryMarkDeleteBeanRepository
    → Verify version matches (if stale, refresh from MySQL)
    → Follow standardRoleTypeId → StandardRoleType { resourceType, strategy }
    → Load ancestry rows → reconstruct ResourceIdPath
    → For each ResourceAction in the system:
        Find ActionInclusion rows where strategy matches
        Compute depth delta (grant depth vs action resource depth)
        Apply includeWhenAbove / includeWhenAt / includeWhenBelow
        If included: insert into AuthorizationSet:
          authSet[domain][resourceType][action][grantId].add(path)

  For each grantId in grants-custom:
    → Resolve CustomRole → CustomRoleAction rows
    → Each action has its own path from CustomRoleActionResourceAncestry
    → Insert directly into AuthorizationSet (no ActionInclusion expansion)

  For each grantId in grants-action:
    → Resolve IdentityResourceAction → single (action, path) pair
    → Insert into AuthorizationSet

  For each grantId in grants-super:
    → Resolve SuperUser → all ResourceActions in domain (or all domains)
    → Insert ALL actions with empty path (covers everything)

  grants-public already known → same expansion for all identities

       │
       ▼
AuthorizationSet (result):
  {
    "io.netfoundry.network": {
      "network": {
        "read":   { sr-uuid → [ ResourceIdPath[network-group/NG-1] ] },
        "update": { sr-uuid → [ ResourceIdPath[network-group/NG-1] ] }
      },
      "endpoint": {
        "read":   { sr-uuid → [ ResourceIdPath[network-group/NG-1] ] },
        "create": { sr-uuid → [ ResourceIdPath[network-group/NG-1] ] }
      }
    }
  }

       │
       ▼
③ Controller method fires (e.g., GET /networks/{id})
  @AuthRead(on = Network.class) @PathVariable UUID networkId

  → ConstraintValidator calls context.isAuthorized(
        domain="io.netfoundry.network",
        resourceType="network",
        action="read",
        targetPath=ResourceIdPath[ network-group/NG-1 → network/NET-2 ]
     )

       │
       ▼
④ Authorization.isAuthorized()   [pure in-memory, nanoseconds]
  grantPaths = authSet["io.netfoundry.network"]["network"]["read"]
             = { sr-uuid → [network-group/NG-1] }

  For each grantPath in grantPaths.values():
    if grantPath.includes(targetPath)?
      → ResourceIdPath[network-group/NG-1].includes(
             ResourceIdPath[network-group/NG-1 → network/NET-2])
      → YES — grant path is a PREFIX of target path
    → return true → ✅ AUTHORIZED

      OR if only owner-dynamic paths exist:
    → check ownerSupplier.get() == identityId → AUTHORIZED/DENIED

       │
       ▼
  true  → request proceeds to service method
  false → ConstraintViolationException → AuthExceptionAdvice → 403 Forbidden

Concrete Example: Alice reads a network in Core Management

Auth Service sees IdentityStandardRole row → emits NF JWT:
{
  "sub": "alice-uuid",
  "grants-standard": "[{\"id\":\"sr-ng1-admin\",\"lm\":1692000000000}]",
  "grants-public": "[{\"id\":\"pg-geo-read\",\"lm\":100}, ...]",
  "grants-super": "[]",
  "grants-action": "[]",
  "grants-custom": "[]",
  "exp": <now + 300>
}

Core Service receives: Authorization: Bearer <NF JWT>

Step 1 — Parse JWT → grants-standard = [{id: sr-ng1-admin, lm: 1692000000000}]

Step 2 — Expand sr-ng1-admin:
  StandardRoleType: Admin on network-group
  Path: network-group/NG-1-uuid
  ActionInclusion for Admin + network.read → includeWhenAbove=true
  (Alice is granted at depth 0 = network-group; network is depth 1 → grant is ABOVE)
  → authSet["io.netfoundry.network"]["network"]["read"][sr-ng1-admin] = {network-group/NG-1}

Step 3 — @AuthRead(on=Network.class) fires:
  targetPath = network-group/NG-1-uuid → network/NET-2-uuid

Step 4 — isAuthorized check:
  grantPath: network-group/NG-1-uuid
  targetPath: network-group/NG-1-uuid → network/NET-2-uuid
  grantPath.includes(targetPath)?  YES (grant is a prefix)
  → ✅ AUTHORIZED — request proceeds

targetPath = network-group/NG-2-uuid → network/NET-99-uuid

grantPath: network-group/NG-1-uuid
grantPath.includes(targetPath)?
  → network-group/NG-1 ≠ network-group/NG-2 → paths diverge at element 0
  → NO match
→ ❌ DENIED — 403 Forbidden

Summary: What Each Layer Contributes to the Authorization Decision

How to Master This Auth Service

This is a structured path to go from "I read the docs" to being the person other teams come to when something breaks or when a new service needs to be onboarded.

Stage 1 — Understand the Mental Model (Week 1)

You can't master code you can't picture. Get these three things rock solid before touching the codebase.

Grant:      network-group/NG-1
API call:   GET /networks/NET-2   → targetPath = network-group/NG-1 → network/NET-2

Does network-group/NG-1 include network-group/NG-1 → network/NET-2 ?
→ YES — grant is a prefix of the target → AUTHORIZED

Now try:
Grant:      network-group/NG-1 → network/NET-2
API call:   GET /networks/NET-9  → targetPath = network-group/NG-1 → network/NET-9
Does it match? → NO — paths diverge at network level → 403

-- Find the StandardRole row
SELECT * FROM StandardRole
WHERE id = UNHEX(REPLACE('<uuid-from-jwt>','-',''));

-- Find the path (ancestry)
SELECT * FROM StandardRoleResourceAncestry
WHERE standardRoleId = UNHEX(REPLACE('<uuid>','-',''));

-- Find who else holds this role
SELECT * FROM IdentityStandardRole
WHERE standardRoleId = UNHEX(REPLACE('<uuid>','-',''));

-- Find what the role template says
SELECT SRT.* FROM StandardRoleType SRT
JOIN StandardRole SR ON SR.standardRoleTypeId = SRT.id
WHERE SR.id = UNHEX(REPLACE('<uuid>','-',''));

GET /auth/v1/authorizations?identityId=<uuid-of-a-network-group-admin>

Stage 2 — Read the Code in the Right Order (Week 2)

Don't read randomly. Follow the request lifecycle in this exact order. For each file: read the test first, then the implementation.

Stage 3 — Make Changes (Week 3–4)

Reading is passive. You become an SME by breaking things and fixing them. Do each of these exercises end-to-end.

Stage 4 — Own the Hard Problems (Month 2)

These are the areas where SME-level knowledge lives. Most engineers never need to touch these — but an SME must own them.

Stage 5 — Become the Go-To Person (Ongoing)

SME status is not a certificate — it is earned by being consistently useful to others. These activities compound over time.