Getting started with API Keys

This page describes how to set up your local environment to experiment with API Keys using the curl command.

Before you begin

  1. Install oauth2l on your local machine so you can interact with the Google OAuth system. The oauth2l command-line tool:

    • Is available only for Linux or macOS
    • Requires Go 1.10.3 or higher

    If you prefer, you can download and install oauth2l on Cloud Shell:

    • A supported version of Go is already installed.
    • The GOPATH environment variable is defined and has been added to the PATH.
  2. Enable API Keys in your Google Cloud project.

    1. In the Cloud Console, go to the APIs & Services > Library page.

      Go to the API Library

    2. Select or create a Cloud project that you will use to call API Keys.
    3. Click Enable.
  3. Create at least one API key for testing.

    1. In the Cloud Console, go to the APIs & Services > Credentials page.

      Go to the Credentials page

    2. Click Create credentials, and then select API key.
    3. Optionally, click Restrict key to restrict and rename the API key.

Create a service account

To configure authentication for API Keys, do the following:

  1. Create a service account.
  2. Assign the service account the API Keys Admin role.
  3. Create a service account key file.

The following steps describe how to do these tasks in the Cloud Console and by using the gcloud command-line tool. For more information about service accounts and keys, see the following:

If you installed oauth2l on Cloud Shell, you might find it easier to create the key file for the service account by running the gcloud tool in Cloud Shell.

Console

  1. In the Cloud Console, go to the Service Accounts page.

    Go to the Service Accounts page

  2. Select the project in which you enabled API Keys.
  3. Click + Create Service Account.
  4. Click Service account name, and enter the name for your service account.
  5. Click Create.
  6. Click Select a role.
  7. In the Type to filter field, enter API Keys Admin.
  8. Click Continue.
  9. Click + Create key.
  10. In the right-side panel, use JSON as the Key type.
  11. Click Create, and then click Close in the dialog box.
  12. Click Done. This creates the service account and downloads its private key to a JSON file.
  13. Move and rename the service account key file to ~/credentials.json.

gcloud

  1. Enter the following to display the project IDs for your Google Cloud projects:

    gcloud projects list
    
  2. Replace PROJECT_ID in the following command to set the default project to the one in which you enabled that API Keys:

    gcloud config set project PROJECT_ID
    
  3. Make sure that the Cloud SDK gcloud tool is authorized to access your data and services on Google Cloud:

    gcloud auth login
    
  4. To create a service account, run the following command and replace SERVICE_ACCOUNT_NAME and My Service Account with the name and display name that you want to use:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
       --display-name "My Service Account"
    

    The command assigns an email address for the service account in the following format:

    SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    

    This email address is required in the subsequent commands.

  5. Add the API Keys Admin role:

    gcloud projects add-iam-policy-binding PROJECT_ID \
      --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
      --role roles/serviceusage.apiKeysAdmin
    
  6. Create a service account key file:

    gcloud iam service-accounts keys create ~/credentials.json \
        --iam-account SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com
    

    For more information about the commands, see gcloud iam service-accounts.

Testing the API Keys API

  1. Verify that your local machine is setup for testing:

    oauth2l header --json ~/credentials.json cloud-platform
    

    On success, oauth2l outputs a token similar to the following that you can use to authenticate with the API:

    Authorization: Bearer y29.xxxxxxx
    
  2. Get the project number for the project in which you enabled API Keys.

  3. Define a convenient shell alias for calling the API:

    alias gcurl='curl -H "$(oauth2l header --json ~/credentials.json cloud-platform userinfo.email)" -H "Content-Type: application/json"'
    
  4. Make a request to get a list of API keys in your project:

    gcurl https://apikeys.googleapis.com/v2/projects/YOUR_PROJECT_NUMBER/locations/global/keys
    

    On success, you get a response similar to the following:

    {
      "keys": [
          {
            "name": "projects/12345678/locations/global/keys/2885bf87-5b84-47fa-92af-08c3e9337349",
            "displayName": "API key 2",
            "createTime": "2019-05-29T22:07:22.036Z",
            "uid": "2885bf87-5b84-47fa-92af-08c3e9337349",
            "updateTime": "2019-05-29T22:07:22.058623Z",
            "restrictions": {
              "androidKeyRestrictions": {}
            },
            "etag": "zHib8eXEMCxe4ayQEbIaZg=="
          },
          {
            "name": "projects/12345678/locations/global/keys/a4db08b7-5729-4ba9-8c08-f2df493465a1",
            "displayName": "API key 1",
            "createTime": "2019-05-29T22:06:58.844Z",
            "uid": "a4db08b7-5729-4ba9-8c08-f2df493465a1",
            "updateTime": "2019-05-29T22:06:58.855103Z",
            "restrictions": {
              "androidKeyRestrictions": {}
            },
            "etag": "0L5KcPMGoNi53K5+FqPxiw=="
          }
      ]
    }
    

Troubleshooting

The following error occurs when the access token for your oauth session has expired:

Request had invalid authentication credentials

To resolve the issue, run the following command:

oauth2l reset

What's next