Access Grants
Control cross-organization access with grants for consultants and partners.
What Are Access Grants?
Access grants are the mechanism that allows consultant organizations to access data belonging to utility or developer organizations. When a utility grants access to a consulting firm, that firm's members can view and work with the utility's data — scoped to specific access levels and, optionally, specific submissions or projects.
Grants are the foundation of GridWonk's multi-organization collaboration model. They enable consultants to work across multiple clients from a single account without sharing credentials or duplicating data.
They do not change who owns a shared submission row. In the project-first lifecycle:
- the utility still owns the review workflow row
- the developer still appears as the applicant side of that row
- the consultant joins through the grant, with scope and audit rules layered on top
An access grant never creates a utility affiliation. Utility-review authority comes from a platform-provisioned utility organization and its active membership; grants only add the scoped client access described below.
An admin-level client grant does not permit changing the client's Workspace appearance. That setting requires direct Owner/Admin membership in the developer or utility organization, or authorized platform support. Previewing or saving colors never widens a grant or changes the sign-in domain. See Workspace appearance.
How grant-based access is decided
How grant-based access is decided
A grant adds scoped access; it never replaces organization membership. Every request must pass the organization, membership, grant, scope, and action checks that apply to it.
Check the target and organization type
The requested resource must belong to the granting client organization, and the action must support consultant access.
Check the receiving membership
The consultant user needs an active, unexpired membership. Viewer is read-only; mutations require Member, Admin, or Owner.
Check the grant
The grant must be active, unexpired, unrevoked, and in scope for the requested submission or project.
Combine role and grant level
Read requires an allowed read path. A grant-aware mutation requires both a mutation-capable receiving role and write or admin grant access.
Apply action-specific rules
Some operations, including project creation, still require direct membership even when a write grant exists.
Source anchors: app/api/_shared/organization-access.ts, lib/auth/grant-scope.ts
Access Levels
Each grant specifies an access level that controls what the receiving organization can do.
| Access Level | View Data | Mutate Scoped Workflows | Admin-Level Grant Operations |
|---|---|---|---|
| Read | Yes | No | No |
| Write | Yes | Yes | No |
| Admin | Yes | Yes | Yes, where the target workflow supports grant-based admin access |
The grant level and the receiving user's membership role are both enforced. A write or admin grant does not make a Viewer a writer: grant-aware mutations require an active Member, Admin, or Owner role in the receiving consultant organization. A grant also does not make that user a member or owner of the client organization.
- Read — View documents, deficiency reports, validation results, and dashboard statistics for the granting organization.
- Write — Everything in Read, plus grant-aware mutations supported by the target workflow when the receiving user is Member-or-higher.
- Some workflows still require direct membership even when you have a write grant; project creation is the main example today.
- Admin — Everything in Write, plus admin-level access for grant-aware workflows that explicitly support it. This is not the same as organization ownership or GridWonk platform-admin access, and it does not include the workspace Features page — feature toggles require direct admin or owner membership in the organization, and settings made by the GridWonk platform team appear read-only there (support can change them).
How Grants Are Created
Only admin or owner members of the granting organization can create access grants. The process works as follows:
- A utility (or developer) org admin uses the consultant access hub or organization grant management UI
- They select the consultant organization to grant access to
- They choose an access level (read, write, or admin)
- Optionally, they scope the grant to specific submission or project records
- Optionally, they set an expiration date
Grants can only be issued to organizations with the consultant organization type. You cannot grant access to another utility or developer organization, or to the internal GridWonk platform organization.
The API also blocks self-grants, duplicate active grants for the same organization pair, and grants to non-consultant receiving organizations.
Grant create and update requests are bounded to 32 KiB before JSON parsing. Project-scoped grants accept at most 500 project identifiers, and each identifier is length-limited before it reaches the database. Invalid or oversized request bodies fail before grant state is read or written.
Submission And Project Scoping
By default, a grant provides access to all grant-aware work within the granting organization. For tighter control, grants can be scoped to specific submission or project records. The consultant access hub labels this field as scoped submission IDs.
When a grant includes project scoping:
- The consultant can only view and interact with the specified submission or project scope
- Other out-of-scope work in the organization remains invisible
- API requests outside the allowed scope return an authorization error
Shared-submission access resolves the submission, application-document, deficiency, and applicant document context before checking the caller's organization or owner-user scope. That keeps legacy applicant documents, project-linked documents, and deficiency findings on one read decision path. Organization API keys can use that path only for organization-visible applicant documents; private and individually shared rows remain user-scoped even when a project grant exists. Grant scoping controls what an API key can reach — whether an organization has API access at all is provisioned by GridWonk and is not something a grant or an organization admin can change. Organization-setting updates are rate-limited separately from grant access and may need to be retried after HTTP 429.
This is useful when a consultant is engaged for a specific interconnection application rather than managing an entire portfolio.
Grant Expiration
Grants can include an optional expiration date. When set:
- The grant remains active until the expiration date passes
- After expiration, all access is automatically revoked — no manual intervention required
- Expired grants still appear in the grant history for audit purposes
- Users attempting to access data through an expired grant receive an authorization error
If no expiration date is set, the grant remains active indefinitely until manually revoked.
Viewing Active Grants
Both granting and receiving organizations can view their grants:
- Granting organizations see a list of all grants they have issued, including the receiving organization name, access level, project scope, and expiration status.
- Receiving organizations (consultants) see a list of all grants they have received, showing which clients have given them access and at what level.
The grant listing supports filtering by direction (granted vs. received) and can optionally include expired grants for audit review.
When a consultant is working through a grant, the workspace shows a grant banner with the access level, granting organization, project scope count, and expiration date when present.
Revoking a Grant
When access needs to be removed, grants use a soft-delete model:
- Revocation sets a
revokedAttimestamp on the grant record - The grant is not physically deleted from the database
- Revoked grants no longer authorize any data access
- The full grant history remains available for compliance auditing
Only admin or owner members of the granting organization can revoke grants.
Audit Trail
Grant records and consultant actions preserve compliance evidence:
- Creation — The grant records who created it, when, and with what parameters
- Access — Consultant actions performed under a grant are recorded in the consultant audit log
- Revocation — Revoked grants preserve their history and record the revocation timestamp
The consultant audit log captures the actor, the consultant organization, the client organization, the grant ID, the action performed, the resource type and ID, and a timestamp for grant-scoped workflow actions.
Who Can Manage Grants
| Action | Viewer | Member | Admin | Owner |
|---|---|---|---|---|
| View grants | Yes | Yes | Yes | Yes |
| Create grants | No | No | Yes | Yes |
| Revoke grants | No | No | Yes | Yes |
Platform administrators (GridWonk staff) can also manage grants across all organizations for support purposes.
Organization Switcher
Consultants use the Organization and role selector to choose a client directly from their accessible organizations. You do not need to select your consulting organization first or visit Consultant Access. The selector shows the active organization and persona so the authorization context is visible before a user opens or changes project data. When a consultant switches to a client organization:
- The dashboard updates to show that client's data
- All actions are performed within the scope of the active grant
- Project-level scoping is automatically enforced
- The grant's access level determines what actions are available
This allows consultants to work across their full client portfolio without logging in and out of separate accounts.
On desktop dashboard and Consultant Access pages, the selector is in the header. In Console and Utility workspaces, expand the sidebar and find it above your account button. Choosing an organization saves it as your default. On production, switching reloads the current page; open Console for a developer client or the Utility workspace for a utility client afterward. Select the client before opening a project link: links do not silently change organization context.
Alternatively, select your consulting organization and open Consultant Access. Under Client Organization Access, inspect the client's level and scope, then choose Switch. This changes the active organization without changing your saved default. The lower Incoming grants list loads with Refresh Grants; an initially empty lower list does not mean you have no access.
Email and bell alerts (when enabled)
New-grant notifications are disabled by default pending approved rollout. When enabled, a new usable grant creates an unread bell alert for each eligible active member. Email is independently controlled. Existing grants and later membership joins do not generate historical alerts.
The alert remains discoverable after login, including with another organization selected. View client access opens /consultant; it does not switch organizations or accept an invitation. Select the receiving consulting organization if needed and choose the client there. Marking read, dismissing, and navigating are separate controls. Read/dismiss choices are saved across devices.
If an alert becomes inaccessible, the inbox explains that it is no longer available instead of reporting a successful update. Repeating an already accepted read or dismissal remains safe. After an account or organization changes in another tab, save your open work before choosing Reload workspace; notifications never silently switch the page to the new context.
If a client is missing, check your signed-in email and active, unexpired consulting membership; then ask the client administrator to confirm the receiving organization, scope, expiration, and revocation state. Reload after a new grant. Email is not an access credential, and stale grants disappear from the actionable inbox. No scheduled expiration means no date was set, not guaranteed permanent access.
If GridWonk asks you to accept updated legal terms, do that before retrying an action or using a client-data API. A valid grant does not bypass that requirement.
Tips
- Start with read access and upgrade to write or admin as the engagement deepens
- Use project-level scoping for short-term or narrowly focused engagements
- Set expiration dates that align with your contract terms
- Review active grants periodically — revoke any that are no longer needed
- Check the consultant audit log if you need to verify what actions a consultant has taken