Skip to main content
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 Allow access grants. The indicator next to the toggle shows which approval flow requests will follow. enable-jit-setting

​
Configure the approval flow

Access grant requests are reviewed with Custom Approval (Workspace > CI/CD > Custom Approval): add a rule under the Request Access Grant source to route them to the right approver. If no rule matches, the workspace Fallback Rules apply. custom-approval-jit
Turning on the project setting requires the bb.projects.update permission — for example a Project Owner or Workspace Admin. Editing approval flows requires bb.settings.set — for example a Workspace Admin.

​
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 Allow access grants enabled, select the database, and run your query. Without permission, the result panel returns permission_denied along with a Request query button.
The button reads Request query only when the project allows access grants and the missing permission is read-only (bb.sql.select / bb.sql.info). Otherwise it reads Request role and opens a role request instead.
permission-denied-request Click it to open the Request access grant 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.
request-data-access-drawer Submit, and Bytebase opens the request issue in a new tab, routed through the Request Access Grant approval flow. Other entry points open the same drawer with the matching option pre-checked: Request unmask in the masking reason popover of a masked cell, Request export on a query result when direct export is disabled, and Request access grant at the top of the Access Grants tab.

​
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. jit-access-request-issue Approval rules under the Request Access Grant 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 Access Grants 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. jit-access-list 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. jit-access-run-results
Only a statement that exactly matches the one in the grant is allowed to run — leading and trailing whitespace is ignored, but any other edit to the SQL, even reformatting, is denied. Use the Run button on the Access Grants list to re-run the approved statement reliably.

​
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 access grant expiration setting (Settings > General, Security section) — the longest an access grant 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.