Scoped API Tokens and Permission Models for Multi-Tenant Configurators

A platform where contractors, owner-operators, and systems integrators all call the same API cannot run on one shared credential. Issue a single API key for every integration, or one org-wide token that covers all actors, and the whole system now depends on that one secret staying safe. The moment it leaks, an attacker gets the full reach of whatever that credential could touch. There's no partial compromise in that setup, only total exposure.

The failure isn't abstract for a configurator running on a data center project. A general contractor's submittal agent, an owner's reporting tool, and a systems integrator's cabling agent might all sit on the same platform, call the same endpoints, and still belong to separate trust domains that must never cross. One contractor's agent should never be able to pull up a peer contractor's open RFI log, even though both are logged into the exact same system. Shared authentication was never built to draw that line. A platform needs a way to tell two authenticated actors apart, not just confirm that both logged in correctly.

Tenant-bound token scoping

The fix is a token built to carry its own rules. A well-formed token holds tenant identity, a defined permission scope, issuance details, and a signature proving it hasn't been tampered with. That combination turns the token into a policy document that travels with the request, not just a key that opens a door.

Putting tenant identity inside the token itself lets the gateway check where a request came from and what it's allowed to touch before it ever reaches a database. No extra lookup call is needed to confirm the request's origin. The token carries the answer already.

Scope works as a ceiling on what the token can ask for. A token scoped to cabling:write cannot call a power:configure endpoint, full stop, even if the person who holds that token also happens to have power-level privileges on their account. A token grants a scope, and the user tied to that token must also be allowed that scope, or the ceiling doesn't hold. Neither side can win on its own. A token can't hand out more access than the issuing user actually has, and a user's broad permissions can't sneak past a narrower token. That pairing lets an administrator issue a tightly scoped credential for one integration without ever exposing the full range of their own account.

Granularity matters as much as the scope rules themselves. A token tied to one project workspace, rather than one user or one whole organization, keeps damage contained if something goes wrong. Different teams on different projects get isolated integration contexts, so a leak in one workspace stays contained there.

Tenant identity and capability scope encoded per actor role

The same person can hold two completely different tokens depending on which tenant context they're working in at that moment, and a configurator has to treat those as unrelated credentials. A user named Sarah, authenticated into Acme Corp, gets a token carrying an org code for Acme Corp and admin-level permissions. The same person, authenticated into Startup Inc, gets a token with Startup Inc's org code and viewer-only access. Same underlying identity, two separate permission sets, kept fully apart by the application.

That separation is visible across the actor roles inside a data center delivery configurator. An owner-operator needs to read across all tenant data and write to configuration parameters, but should have no access to a contractor's internal submittals. A general contractor needs write access to submittals and RFI responses, but only inside their own project, with no read access into a peer contractor's records on that same job. A systems integrator running a fiber routing agent needs write access scoped to cabling within its assigned work package, and should be blocked from a power-configuration endpoint even if the account behind it technically holds that privilege elsewhere. A commissioning agent needs read access to as-built data and write access to acceptance records, with the token itself set to expire once the project reaches acceptance.

None of these roles get defined once, globally, and reused everywhere. The identity provider has to set the org code, role, and permission set correctly at the moment of authentication, for the specific tenant context the user is operating in right then. Everything downstream, the gateway, the application, the database, treats those claims as the final word on what the request is allowed to do.

Enforcing least privilege at the gateway before routing

Checking permissions inside application logic, after a request has already been routed, happens too late to matter. The token's scope needs validation at the gateway, before the request ever reaches a service that might act on it. A misconfigured downstream service should never be the last line of defense against a request it was never supposed to receive.

Permission enforcement generally lands in one of two places: the external API only accepts tokens already scoped to the right user, or the application applies its own access logic before the call goes through. Either way, authenticating an agent isn't the same as authorizing what it does. The tool layer still has to check which tenant, which connection, which tool, and which arguments the agent is allowed to use, on every call.

What happens when that check is missing at the gateway has a real-world precedent. An API token discovered sitting in an unrelated file was used to reach a production system, because the token carried account-wide permissions with no environment isolation built in. Nothing at the gateway checked whether that token's declared scope actually covered the environment it was being used against. Translate that same gap into a data center configurator, where the equivalent system controls live power management: there, the failure is a physical risk, not just a data leak.

A gateway sitting in front of a configurator needs to run four distinct checks before anything else happens. The identity provider sets the right claims (org code, role, permission set) into the token at the moment of authentication. The gateway then enforces those claims before any application logic runs, rejecting any request whose scope doesn't cover what it's asking for. The interface hides controls a user can't use, which cuts down on accidental mistakes but was never meant to stop a deliberate one. The database filters every query by the org code carried in the token, so that even a query that somehow slips past the gateway still can't pull data across tenant lines. The gateway is the first and the mandatory checkpoint. The database layer is a backstop for when something else already failed, not the main defense.

Resource-level permissions versus role-level permissions in configurator workflows

Role-level permissions, admin, member, viewer, describe what a type of user can generally do across the system. Resource-level permissions describe what that same user can do to one specific record, project, or asset. In a multi-tenant configurator, that distinction decides whether two contractors working the same project can see into each other's files.

Take a general contractor's submittal agent holding a token scoped to submittals:write. At the role level, that looks like full write access to submittals. But resource-level enforcement has to narrow that down further, so the write access only applies to submittals that belong to that contractor's own project scope. It cannot extend to an open submittal filed by a different contractor working the same job on the same platform instance. The role says what kind of action is allowed. The resource-level check says which specific records that action can touch.

A data center delivery configurator has several categories of resource that need this exact treatment: RFI records tied to a specific contractor, submittal packages tied to a specific trade, power configuration endpoints tied to a specific system boundary, and asset records tied to a specific operational owner. A fiber routing agent carrying a cabling:write token should never be able to call a power:configure endpoint, and the reason has nothing to do with whether its role is senior enough. The token's resource-level scope simply excludes that class of endpoint outright, regardless of what role sits behind it.

Token lifecycle: issuance, expiration, and the handoff boundary

A token's expiration date should line up with a project milestone, not just a fixed number of days on a calendar. A commissioning agent's credential should expire the moment a project reaches acceptance, at the same instant the operations team's credential activates. That timing turns a handoff that used to depend on someone remembering to update permissions into something the system enforces on its own.

Expiration works as a property that belongs to each individual token, separate from whatever login session the user happens to be running. A token can be set to expire in a day, in thirty days, in a year, or on a specific date chosen at issuance, and once that date passes, the backend rejects the token no matter what scopes it was originally granted.

That structure solves a real handoff problem in data center delivery. Building the DCIM database at handover requires submittals and shop drawings, and those documents often sit inside a construction management platform the operations team loses access to right after project closeout. The DCIM database sits only partly filled in at handover, with gaps that can remain unresolved for months because no one owns the job of closing them.

Time-bounded tokens turn that ownership gap into an enforced boundary. The commissioning agent's token is set to expire at acceptance, marking a formal handoff point. Activate the operations team's token at that same moment, with write access to DCIM, EPMS, and BMS endpoints, and the transfer of responsibility happens on a schedule the system itself tracks, rather than depending on someone remembering to flip a switch. Each token in a multi-actor project stays independently revocable, too, so pulling one token never disturbs a user's normal login session or any other token still active. And once a token is issued, the actual bearer value is shown exactly once, at creation, never again when listing existing tokens afterward. If a token gets compromised, revoking it is the only path back.

Revocation patterns that work without disrupting active integrations

Tokens built to be long-lived and narrowly scoped only work if revoking one doesn't ripple out and break everything else. Pulling a single token should never force a user to log back in, and it should never touch any other token tied to the same account.

Each API token stands as its own independent unit of authorization. Revoking one has no effect on a user's normal login session and no effect on any other token issued to that same user. A token is its own self-contained grant, not a smaller piece cut from one master credential, and the system treats it that way when something goes wrong.

That matters most on a live multi-tenant project, where a contractor, an owner, and an integrator might all be running active integrations against the same platform at the same time. If the contractor's credential gets compromised, revoking it should take down nothing beyond that one credential. The owner's integration keeps running. The integrator's agent keeps working. No one else needs to re-authenticate or wait for new tokens to get issued.

Workspace-scoped tokens narrow the blast radius even further on their own. A leaked token tied to one workspace stays a workspace-level problem. Org-level credentials and any peer workspace's integrations are untouched. Some designs take this a step further with a token family model, where every access token traces back to a revocable family, and invalidating that family at the root instantly invalidates every token descended from it, with no need to wait for an old token to be presented again before the system refuses it.

Routing also plays a direct role in how revocation gets enforced. Atlassian Cloud's architecture requires scoped tokens to route through its API gateway rather than a site-specific URL, and a request sent to the wrong endpoint comes back as a 401 Unauthorized. That same gateway-routing requirement is what makes revocation enforceable in practice: pull a token from the gateway's valid-token list, and it stops working immediately, well before its stated expiration date would have retired it on its own.

Audit patterns that maintain traceability across every actor touching a configuration

Every actor on a shared configurator, every contractor, owner, integrator, and commissioning agent, leaves a trail tied to the specific token that acted on their behalf. Because each token already carries tenant identity, scope, and issuance metadata, a record of which token called which endpoint, at what time, doubles as a record of exactly which tenant and which role performed that action. There's no need to reconstruct intent after the fact. The token already states it.

That traceability depends entirely on the design choices made earlier in the lifecycle. A shared credential used by multiple actors produces a log that says an action happened, but not reliably who performed it. A tenant-bound, scoped token produces a log entry that names the org, the role, and the exact permission exercised, every time. Multiply that across a project with dozens of contractors, integrators, and commissioning agents cycling in and out over many months: one logging outcome produces an audit trail that actually holds up, and the other produces one that's full of guesswork.

Tying expiration to project phase, as covered earlier, adds another layer to that trail. A commissioning agent's token expiring at acceptance doesn't just enforce a permission boundary. It also marks, in the record itself, the precise moment responsibility passed from one actor to the next. For a data center project where regulatory and operational accountability both matter long after handover, that kind of built-in, token-level record is worth more than any after-the-fact reconstruction of who had access to what, and when.