Authenticate API requests

Vertex AI on Google Distributed Cloud (GDC) air-gapped provides many APIs and services that require authentication. Authentication is how you prove your identity to access services by using tokens.

Tokens are digital objects that verify a caller provided proper credentials and that they have been successfully exchanged for the token. The token carries information about the identity of the requesting account and the specific access it is authorized to have.

This page describes how to authenticate to Vertex AI APIs programmatically. Depending on whether you access the Vertex AI APIs as a user or with a service account, this page describes the steps to get an authentication token for your API requests.

Choose one of the following options to get an authentication token:

User account

Follow these steps to get an authentication token with user permissions:

1. Note the endpoint of the API you want to use.

2. Gain access to the Vertex AI service you want to use by granting your user account the corresponding role listed in Prepare IAM permissions.

3. Sign in to Distributed Cloud with the user account you have to interact with the API:

   gdcloud auth login
   

4. Get the authentication token:

   gdcloud auth print-identity-token --audiences=https://ENDPOINT
   

   Replace ENDPOINT with the service endpoint that you use for your organization. For more information, view service status and endpoints.

   Depending on the intended use of the authentication token, you might need to include the port after the service endpoint in the audiences path as follows:

   • If you use a client library for your request, you must include port :443 after the service endpoint in the audiences path. Therefore, the --audiences path in the command must be https://ENDPOINT:443.
   • If you use gRPC, curl, or programmatic REST calls for your request, don't include the port. Therefore, the --audiences path in the command must be https://ENDPOINT.

The output displays the authentication token. Add the token to the header of the command-line requests you make, as in the following example:

-H "Authorization: Bearer TOKEN"

Replace TOKEN with the value for the authentication token that the output displays.

Service account

Follow these steps to get an authentication token with a service account:

1. Note the endpoint of the API you want to use.

2. Set up the service account you want to use to access the Vertex AI service.

3. Grant the service account the corresponding role listed in Prepare IAM permissions to let it gain access to the service you want to use.

4. Get the service key pairs of your service account.

5. Install the google-auth client library:

   pip install google-auth
   

6. Add the following code to a Python script:

   import os
   import google.auth
   from google.auth.transport import requests
   import requests as reqs
   
   os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "PATH_TO_SERVICE_KEY"
   os.environ["GRPC_DEFAULT_SSL_ROOTS_FILE_PATH"] = "CERT_NAME"
   
   # If you use a client library for your request,
   # you must include port :443 after the service endpoint
   # in the audience path.
   audience = "https://ENDPOINT"
   
   creds, project_id = google.auth.default()
   print(project_id)
   creds = creds.with_gdch_audience(audience)
   
   def test_get_token():
     sesh = reqs.Session()
     req = requests.Request(session=sesh)
     creds.refresh(req)
     print(creds.token)
   
   if __name__=="__main__":
     test_get_token()
   

   Replace the following:

   • PATH_TO_SERVICE_KEY: the path to the JSON file that contains the key pairs of your service account.
   • CERT_NAME: the name of the Certificate Authority (CA) certificate file, such as org-1-trust-bundle-ca.cert. You only need this value if you are in a development environment. Otherwise, omit it.

   • ENDPOINT: the service endpoint that you use for your organization. For more information, view service status and endpoints. Depending on the intended use of the authentication token, you might need to include the port after the service endpoint in the audience path as follows:

     • If you use a client library for your request, you must include port :443 after the service endpoint in the audience path. Therefore, the audience path in the script must be "https://ENDPOINT:443".
     • If you use gRPC, curl, or programmatic REST calls for your request, don't include the port. Therefore, the audience path in the script must be "https://ENDPOINT".

7. Save the Python script.

8. Run the Python script to fetch the token:

   python SCRIPT_NAME
   

   Replace SCRIPT_NAME with the name you gave to your Python script, such as token.py.

The output displays the authentication token. Add the token to the header of the command-line requests you make, as in the following example:

-H "Authorization: Bearer TOKEN"

Replace TOKEN with the value for the authentication token that the output displays.