Vertex AI access control with IAM
This page describes how to useIdentity and Access Management (IAM)to manage access to Vertex AI resources. To manage access toVertex AI Workbench instances, seeVertex AI Workbench instancesaccess control.
Overview
Vertex AI uses IAM to manage access toresources. When you plan access control for your resources, consider thefollowing:
You can manage access at the project level or resource level.Project-level access applies to all of the resources in that project.Access to a specific resource only applies to that resource.SeeProject-level versus resource-level access.
You grant access by assigning IAM roles to principals.Predefined roles are available to make it easier to set up access,but custom roles are recommended because you create them, so you canlimit their access to only the permissions that are required.SeeIAM roles.
IAM roles
There are different types of IAM roles that can be used inVertex AI:
Custom roles let you choose aspecific set of permissions, create your own role with those permissions,and grant the role to users in your organization.
Predefined roles let you grant a set of relatedpermissions to your Vertex AI resources at the project level.
Basic roles (Owner, Editor, and Viewer) provideaccess control to your Vertex AI resources at theproject level, and are common to all Google Cloud services.
To add, update, or remove these roles in your Vertex AI project,see the documentation ongranting, changing, andrevoking access.
Custom roles
Custom roles let you choose a specific set of permissions, create yourown role with those permissions, and grant the role to users inyour organization. For more information, seeUnderstandingIAM custom roles.
Use custom roles to grant least-privilege permissions
Predefined roles often contain more permissions than you need.You can create custom roles to grant your principals only thespecific permissions that are required.
For example, you can create a custom role with theaiplatform.endpoints.predict permission, and then assign the role toa service account on an endpoint. This grants the service account theability to call the endpoint for predictions, but not the ability ofcontrolling the endpoint.
aiplatform.endpoints.deploy permission might allow a user to export other deployed or deployable models from the project. If you want to grant the ability to deploy specific models but not others, we recommend using separate projects.Predefined roles for Vertex AI
| Role | Permissions |
|---|---|
Vertex AI Administrator( Grants full access to all resources in Vertex AI |
|
Vertex AI Batch Prediction Service Agent( Vertex AI Batch Prediction Service Agent for serving batch prediction requests. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Colab Enterprise Admin( Admin role of using colab enterprise. |
|
Colab Enterprise User( User role of using colab enterprise. |
|
Vertex AI Colab Service Agent( Gives Vertex AI Colab the proper permissions to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Custom Code Service Agent( Gives Vertex AI Custom Code the proper permissions. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Feature Store EntityType owner( Provides full access to all permissions for a particular entity type resource. Lowest-level resources where you can grant this role:
|
|
Vertex AI Platform Express AdminBeta( Grants admin access to Vertex AI Express |
|
Vertex AI Platform Express UserBeta( Grants user access to Vertex AI Express |
|
Vertex AI Extension Custom Code Service Agent( Gives Vertex AI Extension that executes custom code the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Extension Service Agent( Gives Vertex AI Extension the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Feature Store Admin( Grants full access to all resources in Vertex AI Feature Store Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Viewer( This role provides permissions to read Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Data Writer( This role provides permissions to read and write Feature data. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Instance Creator( Administrator of Featurestore resources, but not the child resources under Featurestores. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store Resource Viewer( Viewer of all resources in Vertex AI Feature Store but cannot make changes. Lowest-level resources where you can grant this role:
|
|
Vertex AI Feature Store UserBeta( Deprecated. Use featurestoreAdmin instead. |
|
Vertex AI Agent Engine Memory Editor RoleBeta( Grants edit access to Memory for Agent Engine. |
|
Vertex AI Agent Engine Memory User RoleBeta( Grants full user access to Memory for Agent Engine. |
|
Vertex AI Agent Engine Memory Viewer RoleBeta( Grants viewer access to Memory for Agent Engine. |
|
Vertex AI Migration Service User( Grants access to use migration service in Vertex AI |
|
Vertex AI Model Monitoring Service Agent( Gives Vertex AI Model Monitoring the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Notebook Executor UserBeta( Grants users full access to schedules and notebook execution jobs. |
|
Notebook Runtime Admin( Grants full access to all runtime templates and runtimes in Notebook Service. |
|
Notebook Runtime User( Grants users permissions to create runtime resources using a runtime template and manage the runtime resources they created. |
|
Vertex AI Notebook Service Agent( Vertex AI Service Agent used to run Notebook managed resources in user project with restricted permissions. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Online Prediction Service Agent( Gives Vertex AI Online Prediction the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Platform Provisioned Throughput AdminBeta( Grants access to use all resources related to Vertex AI Provisioned Throughput |
|
Vertex AI RAG Data Service Agent( Vertex AI Service Agent used by Vertex RAG to access user imported data, Vertex AI, Document AI processors, and Vector Search in the project Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Rapid Eval Service Agent( Vertex AI Service Agent used by GenAI Rapid Evaluation Service to access publisher model endpoints in the user project Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Reasoning Engine Service Agent( Gives Vertex AI Reasoning Engine the proper permissions to function. The aiplatform.reasoningEngines.create IAM permission implies read access to the GCS objects of the consumer project through this service agent. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Service Agent( Gives Vertex AI the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Agent Engine Session Editor RoleBeta( Grants edit access to Session for Agent Engine. |
|
Vertex AI Agent Engine Session User RoleBeta( Grants full user access to Session for Agent Engine. |
|
Vertex AI Agent Engine Session Viewer RoleBeta( Grants viewer access to Session for Agent Engine. |
|
Vertex AI Telemetry Service Agent( Allows Vertex AI Telemetry Service Agent to access telemetry data. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Tensorboard Web App UserBeta( Grants access to the Vertex AI TensorBoard web app. |
|
Vertex AI Tuning Service Agent( Vertex AI Service Agent used for tuning in user project. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI User( Grants access to use all resource in Vertex AI |
|
Vertex AI Viewer( Grants access to view all resource in Vertex AI |
|
Basic roles
The older Google Cloudbasic rolesare common to all Google Cloud services. These roles are Owner, Editor,and Viewer.
Basic roles include thousands of permissions across all Google Cloud services. In production environments, don't grant basic roles unless there is no alternative. Instead, grant the most limitedpredefined roles orcustom roles that meet your needs.Project-level versus resource-level access
You can manage access at the project level or resource level. Youmight also have the ability to manage access at a folder or organization level.
For most Vertex AI resources, access can only be controlled bythe project, folder, and organization. Access to individual resources can begranted only for specific resource types, for example, an endpoint ora featurestore.
Users share control of all resources they can access. For example, if auser registers a model, all other authorized users in the project canaccess, change, and delete the model.
To grant access to resources at the project level, assign one or moreroles to a principal (user, group, orserviceaccount).
For Vertex AI resources that let you grant access atthe resource level, you set an IAM policy onthat resource. The policy defines which roles are assigned to which principals.
Setting apolicy at the resource level doesn'taffect project-level policies. A resource inherits all policies from itsancestry. You can use these two levels of granularity to customize permissions.For example, you can grant users read permissions at the project level so thatthey can read all resources in the project, and then you can grant users writepermissions per resource (at the resource level).
Not all Vertex AI predefined roles and resources supportresource-level policies. To identify which roles can be used on which resources,see thePredefined roles table.
Supported resources
Vertex AI supports Vertex AI Feature Store featurestoreand entity type resources. For more information, seeControl access toVertex AI Feature Store resources.
After granting or revoking access to a resource, those changes take time topropagate. For more information, seeAccess changepropagation.
Resources, service accounts, and service agents
Vertex AI services often manage long-running resourcesthat perform actions, such as running a training job that reads training data,or serving a machine learning (ML) model that reads model weight.Such standalone resources have their own resource identity whenperforming actions. This identity is distinct from the identity ofthe principal that created the resource. Permissions granted to theresource identity define which data and other resources that theresource identity can access, not the permissions of the principalthat created the resource.
By default, Vertex AI resources use service accounts managedby Vertex AI as a resource identity. These service accountsare called Vertex AI service agents, and they are attachedto the project where the resource is created. Users withspecific Vertex AI permissions can create resources that useVertex AI service agents. For some services, you can specifya service account to attach to the resource. The resource uses thisservice account to access other resources and services. To learn more aboutservice accounts, seeservice accounts.
Vertex AI uses different service agents depending on theAPIs being called. Each service agent has specificIAM permissions on the project to which they are tied.These permissions are used by the resource identity to perform actions,and the permissions can include read-only access to all Cloud Storageresources and BigQuery data in the project.
Service accounts
Aservice accountis a special account used by an application or a virtual machine (VM)instance, not a person. You can create and assign permissions to serviceaccounts to provide specific permissions to a resource or application.
For information about using a service account to customize the permissionsavailable to a custom training container or a container that serves onlinepredictions for a custom-trained model, readUse a custom serviceaccount.
Service accounts are identified by an email address.
Service agents
Service agents are automaticallyprovided; they enable a service to access resources on your behalf.
Note: Don't remove default roles and permissions of service agents unless you are sure that they are unnecessary.When a service agent is created, the service agent is granted a predefinedrole for your project. The following table lists Vertex AIservice agents, their email addresses, and their respective roles:
| Name | Used for | Email address | Role |
|---|---|---|---|
| Vertex AI Service Agent | Vertex AI capabilities | service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com | roles/aiplatform.serviceAgent |
| Vertex AI RAG Data Service Agent | Vertex AI RAG accesses user-imported data, Vertex AI, Document AI processors in the project | service-PROJECT_NUMBER@gcp-sa-vertex-rag.iam.gserviceaccount.com | roles/ |
| Vertex AI Custom Code Service Agent | Custom training code Ray on Vertex AI application code | service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com | roles/aiplatform.customCodeServiceAgent |
| Vertex AI Extension Service Agent | Vertex Extensions | service-PROJECT_NUMBER@gcp-sa-vertex-ex.iam.gserviceaccount.com | |
| Cloud AI Platform Notebooks Service Account | Vertex AI Workbench capabilities | service-PROJECT_NUMBER@gcp-sa-notebooks.iam.gserviceaccount.com | roles/notebooks.serviceAgent |
The Vertex AI Custom Code Service Agent is created only if you run custom training codeto train a custom-trained model.
For Vertex AI to perform tasks like training a model using data from a Cloud Storage bucket, it needs permission to read that data. To handle this securely, Vertex AI uses a Google-managed service account called aService Agent to access your resources.When you use the Vertex AI API, this Service Agent is automatically granted IAM roles (likeStorage Object Viewer) on your project. This is expected and necessary for the service to function. This mechanism allows Vertex AI to access the data it needs for tasks you initiate, while your data remains under your project's access control policies.Service agent roles and permissions
See the following roles and permissions that are granted toVertex AI service agents.
| Role | Permissions |
|---|---|
Vertex AI Service Agent( Gives Vertex AI the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI RAG Data Service Agent( Vertex AI Service Agent used by Vertex RAG to access user imported data, Vertex AI, Document AI processors, and Vector Search in the project Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Custom Code Service Agent( Gives Vertex AI Custom Code the proper permissions. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Vertex AI Extension Service Agent( Gives Vertex AI Extension the permissions it needs to function. Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
AI Platform Notebooks Service Agent( Provide access for notebooks service agent to manage notebook instances in user projects Warning: Do not grant service agent roles to any principals exceptservice agents. |
|
Grant Vertex AI service agents access to other resources
Sometimes you need to grant additional roles to a Vertex AI serviceagent. For example, if you need Vertex AI to access aCloud Storage bucket in a different project, you'll need togrant one or more additional roles to the service agent.
Note: If you want your custom training code to obtain an OAuth 2.0 access tokenwith thehttps://www.googleapis.com/auth/cloud-platform scope, then you mustuse acustom service account for training.You can't give this level of access to the Vertex AI Custom Code Service Agent.Role addition requirements for BigQuery
The following table describes the required additional roles needed to beadded to the Vertex AI Service Agent for BigQuerytables or view in a different project or backed by an external data source.
The termhome project refers to the project where theVertex AI dataset or model is located. The termdifferentproject refers to any other project.
| Table type | Table project | Data source project | Role addition required |
|---|---|---|---|
| Native BigQuery table | Home project | N/A | None. |
| Native BigQuery table | Different project | N/A | BigQuery Data Viewer for different project.Learn more. |
| BigQuery view | Home project | N/A | None. |
| BigQuery view | Different project | N/A | BigQuery Data Viewer for different project.Learn more. |
| External BigQuery data source backed by Bigtable | Home project | Home project | Bigtable Reader for home project.Learn more. |
| External BigQuery data source backed by Bigtable | Home project | Different project | Bigtable Reader for different project.Learn more. |
| External BigQuery data source backed by Bigtable | Different project | Different project | BigQuery Reader andBigtable Reader for different project.Learn more. |
| External BigQuery data source backed by Cloud Storage | Home project | Home project | None. |
| External BigQuery data source backed by Cloud Storage | Home project | Different project | Storage Object Viewer for different project.Learn more. |
| External BigQuery data source backed by Cloud Storage | Different project | Different project | Storage Object Viewer andBigQuery Data Viewer for different project.Learn more. |
| External BigQuery data source backed by Google Sheets | Home project | N/A | Share your Sheets file with the Vertex AI service account.Learn more. |
| External BigQuery data source backed by Google Sheets | Different project | N/A | BigQuery Reader for different project andshare your Sheets file with the Vertex AI service account. |
Role addition requirements for Cloud Storage
If you are accessing data in a Cloud Storage bucket in a differentproject, you must give theStorage > Storage Object Viewer role toVertex AI in that project.Learn more.
If you are using a Cloud Storage bucket to receive data from your localcomputer for an import operation, and the bucket is in a different project thanGoogle Cloud project, you must give theStorage > Storage Object Creatorrole to Vertex AI in that project.Learn more.
Grant access to Vertex AI to resources in your home project
To grant additional roles to a service agent forVertex AI in your home project:
Go to theIAM page of the Google Cloud console for your home project.
Select theInclude Google-provided role grants checkbox.
Determine theservice agent you want to grant thepermissions to and click the pencil icon.
You can filter forPrincipal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.
Grant the required roles to the service agent and save your changes.
Grant access to Vertex AI to resources in a different project
When you use data sources or destinations in a different project, you must givethe Vertex AI service agent permissions in that project. TheVertex AI service agent is created after you start the firstasynchronous job (for example, creating an endpoint). You can also explicitlycreate the Vertex AI service agent. For more information, seegcloud beta services identitycreate.This Google Cloud CLI command creates the primary service agent and the customcode service agent. However, only the primary service agent is returned in theresponse.
To add permissions to Vertex AI in a different project:
Go to theIAM page of the Google Cloud console for your home project(the project where you are using Vertex AI).
Select theInclude Google-provided role grants checkbox.
Determine theservice agent you want to grant thepermissions to and copy its email address (listed underPrincipal).
You can filter forPrincipal:@gcp-sa-aiplatform-cc.iam.gserviceaccount.com to find the Vertex AI service agents.
Change projects to the project where you need to grant the permissions.
ClickAdd, and enter the email address inNew principals.
Add all required roles and clickSave.
Provide access to Google Sheets
If you use an external BigQuery data source backed by GoogleSheets, you must share your sheet with the Vertex AI serviceaccount. The Vertex AI service account is created after you startthe first asynchronous job (for example, creating an endpoint). You canalso explicitlycreate the Vertex AI service account by using gcloud CLIby followingthisinstruction.
To authorize Vertex AI to access your Sheets file:
Go to theIAM page of the Google Cloud console.
Look for the service account with the name
Vertex AI Service Agentandcopy its email address (listed underPrincipal).Open your Sheets file and share it with that address.
What's next
- Learn more about IAM.
- Learn about specific IAM permissions andthe operations they support.
- To learn about recommended ways to set up a project for a team, seeSet up a project for a team.
- Get an overview of Vertex AI.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-16 UTC.