FlexGalaxy Resource Names (FRN)

An FRN identifies a resource inside the FlexGalaxy.AI authorization model. FRNs play the same role AWS ARNs play in IAM (see ADR-0017): policy statements name resources with FRNs, PDP requests carry a target resource FRN, and audit events can record the affected resource.

Format

frn:{account-id}:{service}:{resource-path}

Four colon-separated segments, never five:

Segment

Description

Example

frn

Literal prefix. Always exactly frn.

frn

{account-id}

Owning account identifier, or * in policy patterns.

acc-029cea77800e, acc-1, *

{service}

Service namespace.

iam, devices, licensing, audit, org, idc, keycloak, thinghub, s3, profile

{resource-path}

Slash-delimited resource hierarchy. The resource type is part of this path.

user/u-001, device/dev-001, bucket/reports/2026.csv

The Java parser at Frn.parse(...) splits on : into exactly four parts. A value like frn:dotid:acc-029cea77800e:user:alice is invalid because it has five colon-separated parts. Put the resource kind inside {resource-path} instead: frn:acc-029cea77800e:iam:user/alice.

Examples

These examples match FRNs used by the PDP tests and service code:

frn:acc-029cea77800e:iam:user/alice
frn:acc-029cea77800e:iam:group/platform-admins
frn:acc-029cea77800e:iam:policy/pol-7d3b9f12
frn:acc-029cea77800e:iam:access-key/AKIA-9F3B-12C8
frn:acc-target:licensing:device/dev-001
frn:acc-target:audit:event/ev-001
frn:acc-target:org:ou/ou-001
frn:acc-target:idc:permissionset/ps-001
frn:acc-target:keycloak:realm/r-001
frn:acc-1:s3:bucket/reports/2026.csv

The account segment is the owning account, even when another account is making the request.

Policy patterns

Concrete resource FRNs should identify one resource. Policy statement resource patterns may use wildcards:

frn:*:iam:user/*
frn:acc-1:devices:device/*
frn:acc-1:s3:bucket/**

* matches one segment value or one resource-path part. ** is only meaningful inside the resource path, where it matches deeper slash-delimited paths.

Parsing FRNs in your service

Reuse DotID’s shared Java Frn and FrnMatcher classes when you are inside the authorization reactor. If you parse elsewhere, keep the same four-segment shape:

def parse_frn(s: str):
    parts = s.split(":", 3)
    if len(parts) != 4 or parts[0] != "frn":
        raise ValueError(f"not a valid FRN: {s}")
    _, account_id, service, resource_path = parts
    return account_id, service, resource_path

public record Frn(String accountId, String service, String resourcePath) {
    public static Frn parse(String s) {
        String[] parts = s.split(":", 4);
        if (parts.length != 4 || !"frn".equals(parts[0])) {
            throw new IllegalArgumentException("not a valid FRN: " + s);
        }
        return new Frn(parts[1], parts[2], parts[3]);
    }
}

Valid segment characters are intentionally conservative: account and service segments allow letters, digits, _, ., *, and -; the resource path also allows /.

Cross-account FRNs

When a policy in account A references a resource in account B, the FRN’s {account-id} is B, the owning account, not the caller. Cross-account access is denied by default. To enable it, the owning account must publish an explicit trust policy naming the calling account, and the calling identity must still pass its own account’s identity-side checks. Without a matching trust policy, PDP returns decision: DENY, reason: CROSS_ACCOUNT_NO_TRUST.

What FRNs are not

FRNs are identifiers, not URLs. They do not dereference over HTTP, and there is no GET frn:... endpoint.

To look up the resource behind a DotID FRN, call the owning service’s public API using the account-scoped route. For example:

GET /iam/v1/accounts/{accountId}/users/{userId}
GET /iam/v1/accounts/{accountId}/iam-policies/{policyId}
GET /audit/v1/accounts/{accountId}/audit-events

Other service namespaces use their own public APIs. Treat FRNs as opaque authorization identifiers you pass around, not as fetchable URLs.

See also