Access Grants

An access grant is a temporary, elevated privilege bound to specific resources: it authorizes exactly one read-only statement on selected databases, optionally with permission to see the result unmasked or export it, and it expires on its own. Where a role gives standing capabilities, an access grant exists only through approval and only for a limited time — the mechanism behind just-in-time data access.

​

Enable access grants

In the project, click Settings on the left sidebar, find Security & Policy, and turn on Just-In-Time access — this lets project members request access grants. The indicator next to the toggle shows which approval flow requests will follow.

​

Configure the approval flow

Access grant requests are reviewed with Custom Approval (Workspace > CI/CD > Custom Approval): add a rule under the Request Just-In-Time Access source to route them to the right approver. If no rule matches, the workspace Fallback Rules apply.

​

Request an access grant

When you don’t have permission to query a database in SQL Editor, you can request an access grant for a single statement. In SQL Editor, choose the project with Just-In-Time access enabled, select the database, and run your query. Without permission, the result panel returns permission_denied along with a Request just-in-time access button. Click it to open the Request Data Access drawer, pre-filled with the database, statement, and a default expiration. Review and complete:

• Databases — the targets you need to access.
• Statement — the SQL to run. Only read-only statements are allowed.
• Unmask — see unmasked sensitive data in the result.
• Export — also export the query result (see just-in-time data export).
• Expiration — how long the grant stays valid once approved: 1 hour, 4 hours, 1 day, 7 days, or a custom date.
• Reason — the justification reviewers see; required.

Submit, and Bytebase opens the request issue in a new tab, routed through the Request Just-In-Time Access approval flow. You can also start a request from the masking reason popover (pre-selecting Unmask), or from the export flow when direct export is disabled.

​

Approval

The approver sees the requested databases, the exact statement, the granted permissions (including any Unmask or Export), the expiration, and the requester’s reason. Approval rules under the Request Just-In-Time Access source can match the request, for example:

• request.data_export == true — the request includes export.
• request.unmask == true — the request includes unmasking.

Conditions can also match the target with resource.database_name, resource.table_name, and similar attributes.

​

Use the grant

Open the Just-In-Time Access tab — the shield icon on the SQL Editor left sidebar — to track your requests. Each shows its status (Pending while awaiting approval, Active once approved and usable), the databases, any Export or Unmask badge, the time left before expiration, and a link to the approval issue. Once a grant is Active, click Run to execute its approved statement; if the grant includes Export, you can export the result. The grant stays usable until it expires.

​

Review and revoke

To review every access grant in a project, go to Data Access > Access Grants in the project sidebar. Revoking an active grant requires the bb.accessGrants.revoke permission — Project Owner, Workspace Admin, or Workspace DBA.

​

Expiration

An access grant expires automatically. For preset durations, the countdown starts when the request is approved, not when it is submitted. The expiration a member can request is bounded by the workspace Maximum request expiration setting (Settings > General, Security section) — “the maximum period a data access request can remain valid”. This is a separate setting from the maximum role expiration that caps role bindings. The audit log records each query and export, including which access grant authorized it.