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,seeUsing API keys.

Before you begin

The page usescurl 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 theCreateKey method. The method requires aKey parameter.You can only specifydisplayName andrestrictions fields of theKey object.TheCreateKey isn't a synchronous method. Instead, when you issue a call toCreateKey, you initiate a long-runningoperation. The following exampleissues aCreateKey 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 makeoperations.getcalls with the value from thename field. When the response fromoperations.getcontains"done": true, theresponse object contains aKey, 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 theresponse object:

• Thename field contains a unique identifier for the API key. You use thevalue in thename field in the other methods that require akey name. This value isn't displayed in the Google Cloud console, but you cancall theListKeys method toget thenames for all of your API keys. TheKey.name field is always in thefollowing format:projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.
• ThedisplayName field maps to theName field in theGoogle Cloud console, so you might want to provide adisplayName whenyou callCreateKey.
• ThekeyString field contains the string that you send to the APIs thatrequire an API key. ThekeyString maps to theAPI key field in theGoogle Cloud console. You can call theGetKeyStringmethod to get thekeyString for an API key.
• Theetag field contains a checksum computed by the server based on thecurrent value of the key. Please pass theetag value when you callUpdateKeyandDeleteKey methods.

User-specified key id

You can specify akeyIdas a query parameter forCreateKey method. When specified, the value becomes the finalcomponent of theKey.name.

For example, consider the following call toCreateKey:

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, theKey.name field has the following value:

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

Updating the display name

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

The following example illustrates how to callUpdateKey:

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 fromoperations.get contains"done": true, theresponsecontains anKey object with the updateddisplayName.

Deleting an API key

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

The following example illustrates how to callDeleteKey:

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

When the response fromoperations.get contains"done": true, theresponseis 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 asDELETED can't be used, but it isn't completelyremoved from our system either. To list the API keys that still exist but thatare marked adDELETED, setshow_deleted to true forListKeys 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 youcallUndeleteKey, you initiate a long-running operation that marks the key asACTIVE.

The following example illustrates how to callUndeleteKey:

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