Creating and managing API keys

This page explains how to create and manage API keys using the API Keys API.

For information on how to use an API key with your calls to Google Cloud APIs, see Using API keys.

Before you begin

The page uses curl with the oauth2l command-line tool to send requests to the API Keys' API. See Getting started with the API Keys for details on getting set up to experiment with the API.

Creating an API key

You can create an API key by using the CreateKey method. The method requires a Key parameter. You can only specify displayName and restrictions fields of the Key object. The CreateKey isn't a synchronous method. Instead, when you issue a call to CreateKey, you initiate a long-running operation. The following example issues a CreateKey call to create an API key with no restrictions:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys -X POST -d '{"displayName" : "Example API key"}'

On success, the method returns a long-running operation in the response. As described in Polling long running operations, you repeatedly make operations.get calls with the value from the name field. When the response from operations.get contains "done": true, the response object contains a Key, similar to the following:

{
  "name": "operations/akmf.p7-103621867718-06f94db2-7e91-4c58-b826-e6b80e4dc3eb",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key",
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

In the response object:

  • The name field contains a unique identifier for the API key. You use the value in the name field in the other methods that require a key name. This value isn't displayed in the Google Cloud Console, but you can call the ListKeys method to get the names for all of your API keys. The Key.name field is always in the following format: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
  • The displayName field maps to the Name field in the Cloud Console, so you might want to provide a displayName when you call CreateKey.
  • The keyString field contains the string that you send to the APIs that require an API key. The keyString maps to the API key field in the Cloud Console. You can call the GetKeyString method to get the keyString for an API key.
  • The etag field contains a checksum computed by the server based on the current value of the key. Please pass the etag value when you call UpdateKey and DeleteKey methods.

User-specified key id

You can specify a keyId as a query parameter for CreateKey method. When specified, the value becomes the final component of the Key.name.

For example, consider the following call to CreateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?keyId=my-test-key1 -X POST -d '{"displayName" : "Example API key"}'

For this example, the Key.name field has the following value:

    "name": "projects/PROJECT_NUMBER/locations/global/keys/my-test-key1"

Cloning an API key

To make a copy of an API key in the same Cloud project, you use the CloneKey method. When you call CloneKey, you initiate a long-running operation that creates a key with the same displayName and restrictions as the original key, but new name and keyString values.

The following example illustrates how to call CloneKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:clone -X POST

When the response from operations.get contains "done": true, the response contains the new Key object.

The new key has the same displayName and restrictions as the original key, but a new name and keyString.

Updating the display name

To change the displayName of an API key or to add a displayName to an API key that was created without one, call the UpdateKey method. When you call UpdateKey, you initiate a long-running operation that updates the key.

The following example illustrates how to call UpdateKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?updateMask=displayName -X PATCH -d '{"displayName": "New display name", "etag" : "ETAG"}'

When the response from operations.get contains "done": true, the response contains an Key object with the updated displayName.

Deleting an API key

To delete an API key, use the DeleteKey method. When you call DeleteKey, you initiate a long-running operation that marks the key as DELETED.

The following example illustrates how to call DeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?etag="ETAG" -X DELETE

When the response from operations.get contains "done": true, the response is similar to the following:

{
  "name": "operations/akmf.cdabc4df-cbff-4420-8c7e-65dc832c945d",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.api.apikeys.v2.Key"
    "name": "projects/PROJECT_NUMBER/locations/global/keys/aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "displayName": "Example API key",
    "keyString": "----REDACTED----",
    "createTime": "2021-03-23T17:39:46.721099Z",
    "uid": "aecd7943-98ff-4ce2-a876-ec1b37c671ca",
    "updateTime": "2021-03-23T17:39:47.046746Z",
    "deleteTime": "2021-03-24T22:35:37.290544Z",
    "etag": "k0bsYGkIvSxDVwNxyw49NQ=="
  }
}

An API key that is marked as DELETED can't be used, but it isn't completely removed from our system either. After 30 days, the API key is permanently deleted. You can add a filter to the ListKeys method to return API keys that are marked as DELETED:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID?filter=state:DELETED

Restoring an API key

To restore an API key before it is permanently deleted, call the UndeleteKey method. When you call UndeleteKey, you initiate a long-running operation that marks the key as ACTIVE.

The following example illustrates how to call UndeleteKey:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys/KEY_ID/:undelete -X POST

What's next