Getting started with API Keys API

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 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 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 console and by using the Google Cloud CLI. 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 CLI in Cloud Shell.

Console

  1. Create a service account:

    1. In the console, go to the Service Accounts page.

      Go to the Service Accounts page

    2. Select your project.
    3. Click Create Service Account.
    4. In the Service account name field, enter a name. The console fills in the Service account ID field based on this name.
    5. Optional: In the Service account description field, enter a description for the service account.
    6. Click Create and continue.
    7. Click the Select a role field and select API Keys Admin.
    8. Click Done to finish creating the service account.

  2. Download a JSON key for the service account you just created:

    1. In the console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.

      Make sure to store the key file securely, because it can be used to authenticate as your service account.

    5. Move and rename the service account key file to ~/credentials.json.

    6. Click Close.

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 Google Cloud CLI gcloud CLI 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