Creating and managing API keys | API Keys API Documentation

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

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 and the Google Cloud CLI to send requests to theAPI Keys API. SeeGetting started with the API Keysfor 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 aKey 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 exampleissues 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. Asdescribed inPolling long running operations, yourepeatedly make operations.getcalls with the value from the name field. When the response from operations.getcontains "done": true, the response object contains a Key, similar to thefollowing:

{ "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 thevalue in the name field in the other methods that require akey name. This value isn't displayed in the Google Cloud console, but you cancall the ListKeys method toget the names for all of your API keys. The Key.name field is always in thefollowing format: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
The displayName field maps to the Name field in theGoogle Cloud console, so you might want to provide a displayName whenyou call CreateKey.
The keyString field contains the string that you send to the APIs thatrequire an API key. The keyString maps to the API key field in theGoogle Cloud console. You can call theGetKeyStringmethod to get the keyString for an API key.
The etag field contains a checksum computed by the server based on thecurrent value of the key. Please pass the etag value when you call UpdateKeyand DeleteKey methods.

User-specified key id

You can specify akeyIdas a query parameter for CreateKey method. When specified, the value becomes the finalcomponent 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"

Updating the display name

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

Deleting an API key

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

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 responseis 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 completelyremoved from our system either. To list the API keys that still exist but thatare marked ad DELETED, set show_deleted to true for ListKeys method:

gcurl https://apikeys.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/keys?show_deleted=true

After 30 days, the API key is permanently deleted.

Restoring an API key

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

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

Getting information about API keys
Adding restrictions to API keys
Viewing Cloud Audit Logs
Troubleshooting

Creating and managing API keys | API Keys API Documentation | Google Cloud (2024)