Generate an API key

Vikki Paterson, Chloe Poulter

Users click a primary Generate button. Consider displaying a Generating… state if the API key takes time to generate.

Once the API key is generated it displays in a modal. Include a Copy button.

You can ask a user to provide a descriptive name before the key is generated. This is particularly useful in instances where a user may have keys for several applications stored in the same location.

When the user names the API key or provides other information before clicking generate, the API key is presented after the user clicks generate, in a new modal view.

Some API keys cannot be retrieved after creation. Include an appropriate warning to the user for the retrieval use case. All of these use cases can be combined with a download link (for example as a .txt or JSON file).

If a user can retrieve the API key at a later date, within the product (i.e. an API key management page), inform the user that this is the case.
Consider including a link to the retrieval location.

If a user can retrieve the API key at a later date, by accessing a separate interface, such as OpenShift, you should inform them here and provide a link to instructions for doing so.

If a user cannot retrieve the API key in the future, warn them in the modal. Provide the user the option to download the key as JSON.

A user may want to limit the access an application or service is granted. Restricted access allows a user to assign specific access control and permissions before the API key is generated.

Restricted access options vary widely and are not specified in this pattern. Options should be provided in the modal before the user clicks generate. To avoid scrolling in the modal, a multi-step modal can be used, with a progress indicator.

Try to present restricted access options in the following order. Not all options will be required in each case.

In some use cases, it can be helpful to also show the user the API key in context, after the modal is closed. In this situation, the key should be displayed near the “Generate” button.

The user may also need the option to generate a new API key.

Some products and platforms may include an API key management page. This is a central location where API keys can be created, reviewed, or edited.

The location of the API key management page will vary according to the product information hierarchy. Consider where users would expect to administrate access to the product, for example within a “settings”, “access” or similar navigation item.

In the management page, keys are typically listed in a data table, using a recognisable name or the name of the application which the user specified.

After an API key has been generated, some products may enable a user to edit the options associated with it. This may include the name of the connected application, the name of the API key, and restricted access options.
Editing an API key does not allow the user to change the key contents.

The edit action may be accessible in the context of creation, or from an API key management page.
The change to the API key is then “saved”.