This document describes how to authenticate to Cloud Translation programmatically. How you authenticate to Cloud Translation depends on the interface you use to access the API and the environment where your code is running.

For more information about Google Cloud authentication, see theAuthentication methods.

API access

Cloud Translation supports programmatic access. You can access the API in the following ways:

• Client libraries
• REST

Client libraries

TheCloud Translation - Advanced client libraries provide high-level language support for authenticating to Cloud Translation programmatically. To authenticate calls to Google Cloud APIs, client libraries supportApplication Default Credentials (ADC);the libraries look for credentials in a set of defined locations and use those credentialsto authenticate requests to the API. With ADC, you can makecredentials available to your application in a variety of environments, such as localdevelopment or production, without needing to modify your application code.

REST

You can authenticate tothe Cloud Translation API by using your gcloud CLI credentials or by usingApplication Default Credentials. For more information about authentication for REST requests, seeAuthenticate for using REST. For information about the types of credentials, seegcloud CLI credentials and ADC credentials.

API keys

API keys provide a way to associate an API call with a project, which is used for billing and quota purposes, without determining the identity of the caller. API keys can be used only with API methods that support API keys.

Cloud Translation supports API keys for the following API methods:

• All methods for the Cloud Translation - Basic API (v2) support API keys, suchastranslate anddetect. TheCloud Translation - Advanced API (v3) does not support API keys.

For general information about using API keys, seeAuthenticate using API keys.

User credentials and ADC for Cloud Translation

One way to provide credentials to ADC is to use the gcloud CLI to insert your user credentials into a credential file. This file is placed on your local file system where ADC can find it; ADC then uses the provided user credentials to authenticate requests. This method is often used for local development.

If you use this method, you might encounter an authentication error when you try to authenticate to Cloud Translation. For more information about this error and how to address it, seeUser credentials not working.

Set up authentication for Cloud Translation

How you set up authentication depends on the environment where your code is running.

The following options for setting up authentication are the most commonly used. For more options and information about authentication, seeAuthentication methods.

Before you complete these instructions, you must complete the basic setup for Cloud Translation, as described inSet up Cloud Translation.

For a local development environment

You can set up credentials for a local development environment in the following ways:

• User credentials for client libraries or third-party tools
• User credentials for REST requests from the command line
• Service account impersonation

Client libraries or third-party tools

Set upApplication Default Credentials (ADC) in your local environment:

1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

   gcloudinit

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloudauthapplication-defaultlogin

   You don't need to do this if you're using Cloud Shell.

   Note: If the gcloud CLI prints a warning that your account doesn't have theserviceusage.services.use permission, then some gcloud CLI commands and client libraries might not work. Ask an administrator to grant you the Service Usage Consumer IAM role (roles/serviceusage.serviceUsageConsumer), then run the following command:

   gcloudauthapplication-defaultset-quota-projectPROJECT_ID

   If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

   A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

For more information about working with ADC in a local environment, seeSet up ADC for a local development environment.

REST requests from the command line

When you make a REST request from the command line, you can use your gcloud CLI credentials by includinggcloud auth print-access-token as part of the command that sends the request.

The following example lists service accounts for the specified project. You can use the same pattern for any REST request.

Before using any of the request data, make the following replacements:

• PROJECT_ID: Your Google Cloud project ID.

To send your request, expand one of these options:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project:PROJECT_ID" \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts" | Select-Object -Expand Content

For more information about authenticating using REST and gRPC, seeAuthenticate for using REST. For information about the difference between your local ADC credentials and your gcloud CLI credentials, seegcloud CLI authentication configuration and ADC configuration.

Service account impersonation

In most cases, you can use your user credentials to authenticate from a local development environment. If that is not feasible, or if you need to test the permissions assigned to a service account, you can use service account impersonation. You must have theiam.serviceAccounts.getAccessToken permission, which is included in theService Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM role.

You can set up the gcloud CLI to use service account impersonation by using thegcloud config set command:

gcloudconfigsetauth/impersonate_service_accountSERVICE_ACCT_EMAIL

For select languages, you can use service account impersonation to create a local ADC file for use by client libraries. This approach is supported only for the Go, Java, Node.js, and Python client libraries—it is not supported for the other languages. To set up a local ADC file with service account impersonation, use the--impersonate-service-account flag with thegcloud auth application-default login command:

gcloudauthapplication-defaultlogin--impersonate-service-account=SERVICE_ACCT_EMAIL

For more information about service account impersonation, seeUse service account impersonation.

On Google Cloud

To authenticate a workload running on Google Cloud, you use the credentials of the service account attached to the compute resource where your code is running, such as a Compute Engine virtual machine (VM) instance. This approach is the preferred authentication method for code running on a Google Cloud compute resource.

For most services, you must attach the service account when you create the resource that will run your code; you cannot add or replace the service account later. Compute Engine is an exception—it lets you attach a service account to a VM instance at any time.

Use the gcloud CLI to create a service account and attach it to your resource:

1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

   gcloudinit

   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

2. Set up authentication:

   1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin).Learn how to grant roles.

   2. Create the service account:

      gcloudiamservice-accountscreateSERVICE_ACCOUNT_NAME

      ReplaceSERVICE_ACCOUNT_NAME with a name for the service account.

   3. To provide access to your project and your resources, grant a role to the service account:

      gcloudprojectsadd-iam-policy-bindingPROJECT_ID--member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"--role=ROLE

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • ROLE: the role to grant
      Note: The--role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant apredefined role orcustom role that meets your needs.
   4. To grant another role to the service account, run the command as you did in the previous step.

   5. Grant the required role to the principal that will attach the service account to other resources.

      gcloudiamservice-accountsadd-iam-policy-bindingSERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com--member="user:USER_EMAIL"--role=roles/iam.serviceAccountUser

      Replace the following:

      • SERVICE_ACCOUNT_NAME: the name of the service account
      • PROJECT_ID: the project ID where you created the service account
      • USER_EMAIL: the email address for a Google Account

3. Create the resource that will run your code, and attach the service account to that resource. For example, if you use Compute Engine:

   Create a Compute Engine instance. Configure the instance as follows:
   • ReplaceINSTANCE_NAME with your preferred instance name.
   • Set the--zone flag to thezone in which you want to create your instance.
   • Set the--service-account flag to the email address for the service account that you created.

   gcloudcomputeinstancescreateINSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL

For more information about authenticating to Google APIs, seeAuthentication methods.

On-premises or on a different cloud provider

The preferred method to set up authentication from outside of Google Cloud is to use workload identity federation. For more information, seeSet up ADC for on-premises or another cloud provider in the authentication documentation.

Access control for Cloud Translation

After you authenticate to Cloud Translation, you must be authorized to access Google Cloud resources. Cloud Translation uses Identity and Access Management (IAM) for authorization.

For more information about the roles for Cloud Translation, seeAccess control with IAM. For more information about IAM and authorization, seeIAM overview.

What's next

• Learn aboutGoogle Cloud authentication methods.
• See a list ofauthentication use cases.