Token authentication lets you secure requests to Vertex AI services on
Google Distributed Cloud (GDC) air-gapped. This process validates your API requests by
verifying your identity and authorizing your interactions with the
Vertex AI API.

This document is for application developers within application operator groups
who configure application and development environments to enable AI features.
For more information, see [Audiences for GDC air-gapped
documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/resources/audiences).

## Before you begin

To authenticate API requests and configure service accounts, request the
necessary permissions from your administrator. Also make sure that you have your
project set up for Vertex AI. For more information, see
[Set up a project for Vertex AI](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-set-up-project.md.txt).

- Make sure to update your local trust store before you set up authentication in your development environment.

### Request IAM roles

Contact your IAM Project Admin to request the following roles in your project
namespace:

- **IAM Project Admin** (`project-iam-admin`): create service accounts and manage role bindings in the project namespace.
- **Vertex AI OCR Developer** (`ai-ocr-developer`): authenticate requests to the OCR API.
- **Vertex AI Speech Developer** (`ai-speech-developer`): authenticate requests to the Speech-to-Text API.
- **Vertex AI Text Embedding Developer** (`ai-text-embedding-developer`): authenticate requests to the `Text-Embedding-Gecko` model.
- **Vertex AI Text Embedding Multilingual Developer** (`ai-text-embedding-multilingual-developer`): authenticate requests to the `Text-Multilingual-Embedding` model.
- **Vertex AI Translation Developer** (`ai-translation-developer`): authenticate requests to the Vertex AI Translation API.
- **Vertex AI Prediction User** (`vertex-ai-prediction-user`): authenticate prediction requests to Online Prediction models.

For more information about these roles, see [Prepare IAM permissions](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-ao-permissions.md.txt).

## Authenticating to Vertex AI services

Interactions with Vertex AI services are done through authentication tokens. Tokens are digital objects that verify your identity and authorization after you provide valid credentials. The token carries specific information about your account and the permissions it has to access and operate with services and resources.

There are two ways you can set up authentication:

- [Authenticate with your user account](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt#authenticate-with-user-account)
- [Authenticate with your service account](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt#authenticate-with-service-account)

### Authenticate with your user account

The following guides you through getting an authentication token for your user account:

1. Note [the endpoint of the API](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt) you want to use.

2. Gain access to the Vertex AI service or Generative AI model you want to use by granting your user account the corresponding role listed in [Prepare IAM permissions](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-ao-permissions.md.txt).

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

   ```bash
   gdcloud auth login
   ```
4. Get the authentication token:

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

   Replace `ENDPOINT` with the API endpoint that you use for your organization. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).

   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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt) 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:

   ```bash
    -H "Authorization: Bearer TOKEN"
   ```

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

### Authenticate with your service account

The following guides you through getting an authentication token for your service account:

1. Note [the endpoint of the API](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt) you want to use.

2. [Set up the service account](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-set-up-project.md.txt#set-up-service) you want to use to access the Vertex AI service or Generative AI model.

3. Grant the service account the corresponding role listed in [Prepare IAM permissions](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-ao-permissions.md.txt) to let it gain access to the service or model you want to use.

4. [Get the service key pairs of your service account](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/iam/service-identities.md.txt#list_credentials_for_service_accounts).

5. Set the following environment variable:

   ```bash
   export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_SERVICE_KEY
   ```

   Replace `PATH_TO_SERVICE_KEY` with the path to the JSON
   file that contains the key pairs of your service account.
6. Install the `google-auth` client library:

   ```bash
   pip install google-auth
   ```
7. Add the following code to a Python script:

   ```python
   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 API endpoint that you use for your organization. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt). 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](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt) 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"`.
8. Save the Python script.

9. Run the Python script to fetch the token:

   ```bash
     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:

   ```bash
    -H "Authorization: Bearer TOKEN"
   ```

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