BigQuery setup
Create the read-only scanner service account. Toggle between Google Cloud Console steps and copy-ready gcloud commands.
Use this page to create the scanner identity. Pick Console if you prefer clicks. Pick gcloud CLI if you prefer Cloud Shell or a local SDK.
Replace <PROJECT_ID> in every command with the ID (not the name) of the project that will own the service account. In SlashPeak, the same steps run in the setup wizard under BigQuery: pick the access level, follow the Google Cloud setup, then paste the key.
Enable APIs first
Turn on the BigQuery API and the Cloud Resource Manager API for <PROJECT_ID> first. Turning an API on is free and gives no access by itself. See Enable Google APIs.
Do not use a primitive role
Do not grant Editor, Owner, or roles/bigquery.dataViewer. Create the custom roles below so the permission set stays exact and reviewable.
- 1
Open Service Accounts
Sign in to Google Cloud Console. Select the GCP project that will own the service account (this is often your BigQuery admin or billing project). Go to IAM & Admin → Service Accounts.
- 2
Create the service account
Click Create Service Account. Set the name to slashpeak-readonly-account (or any name your org requires). Skip “Grant this service account access to project” on this screen — you will attach a custom role next. Click Done.
- 3
Create a custom role with the necessary permissions
Go to IAM & Admin → Roles → Create Role. In the console, set Title to “SlashPeak readonly necessary”, ID to slashpeakReadonlyNecessary and Role launch stage to General Availability. Add only these atomic permissions: bigquery.jobs.create, bigquery.jobs.listAll, bigquery.datasets.get, bigquery.tables.get, bigquery.tables.list, bigquery.reservations.list, resourcemanager.projects.get, bigquery.readsessions.create, bigquery.readsessions.getData. Do not add roles/bigquery.dataViewer. Save the role, then grant it to the service account (IAM → Grant access). A project custom role works only in its own project, so repeat this step in every project you want scanned, or use Organization level.
- 4
Optional: add the metadata APIs role
To unlock Resource Manager tags, Data Lineage, Knowledge Catalog, and BigQuery audit logs, create a second custom role with: bigquery.capacityCommitments.list, bigquery.reservationAssignments.list, resourcemanager.hierarchyNodes.listEffectiveTags, datalineage.locations.searchLinks, dataplex.entries.list, logging.privateLogEntries.list. In the console, set Title to “SlashPeak optional”, ID to slashpeakOptional and Role launch stage to General Availability. Grant it the same way. Scans still work if you skip this.
- 5
Create a JSON key
Open the service account → Keys → Add key → Create new key → JSON. Download the file. Treat it as a secret: do not commit it, and rotate it if it leaks.
- 6
Paste the key in SlashPeak
Open Connect BigQuery in SlashPeak. Paste the full JSON. Click Test Connection. SlashPeak lists GCP projects, checks IAM, and lets you choose which granted projects to scan.
Suggested service account name
slashpeak-readonly-accountNecessary IAM permissions
bigquery.jobs.createRun INFORMATION_SCHEMA queries
bigquery.jobs.listAllRead every user's job history
bigquery.datasets.getRead dataset metadata
bigquery.tables.getRead table metadata
bigquery.tables.listList tables in a dataset
bigquery.reservations.listList slot reservations
resourcemanager.projects.getRead this project's metadata
bigquery.readsessions.createOpen a Storage Read session
bigquery.readsessions.getDataStream rows from a Storage Read session
Optional IAM permissions (metadata APIs)
Not required to connect. These unlock org/folder tags, Dataplex lineage, Knowledge Catalog, and BigQuery audit logs (Admin Activity and Data Access). Scans keep working without them.
bigquery.capacityCommitments.listList capacity commitments
bigquery.reservationAssignments.listList reservation assignments
resourcemanager.hierarchyNodes.listEffectiveTagsRead inherited Resource Manager tags
datalineage.locations.searchLinksSearch Data Lineage links
dataplex.entries.listList Dataplex catalog entries
logging.privateLogEntries.listRead BigQuery Data Access audit logs
After the key exists
- Open Connect BigQuery while signed in to SlashPeak.
- Paste the entire JSON file, including
type,project_id,private_key, andclient_email. - Click Test connection.
- Select the green projects to include, then Save connection.
Full UI notes: Connect in SlashPeak.
Multiple projects
The create-service-account command runs once. With project-level access, the role must be granted on every project you want scanned.
A custom role created in one project can only be granted inside that project. For project B, create the same role in project B (run the create-role command with --project=<PROJECT_B_ID>), then bind it there to the service account from the home project:
serviceAccount:slashpeak-readonly-account@HOME_PROJECT_ID.iam.gserviceaccount.com
With more than a few projects, use Organization level access below instead. It needs one role on the organization.
Project or organization access
Connect BigQuery first asks Where will you grant access?
- Project level: grant the custom role on each project you want scanned. Best for a few projects.
- Organization level (the default in SlashPeak): grant the scanner role on the project that owns the service account, plus one org role on the organization. Every project is covered, including new ones. Recommended for 3 or more projects. The org role holds
bigquery.jobs.listAll,bigquery.datasets.get,bigquery.tables.get,bigquery.tables.list, andresourcemanager.projects.get(used only by the connection test to find your projects).
With project-level access, the test screen lists only the projects where the key has resourcemanager.projects.get. Grant it at folder or organization scope if you want the test screen to list every project, not only the key’s home project.