Generate an API key
When designing for the generation of API keys, ensure users know what the key is created for, the security implications, and the end destination of the key.
- General access keys
- Restricted access keys
- Show the API key in context (optional)
- API key management page (optional)
- Edit an API key (optional)
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.
- Display two parts to the API key where required
- Display an encoded version of the key
- Provide information text about the API key
- Allow users to toggle the visibility of the key
- Provide a secondary link to download the key
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).
API key can be retrieved in the product
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.
API key can be retrieved via another platform (i.e. OpenShift, IBM Cloud)
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.
API key cannot be retrieved at a later date
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.
- (Optional) Name the API key or application. Allow the user to specify a recognisable name for the API key, or the application, so that they can recognise it later.
- (Optional) Choose the actions the API key permits. Common options are “Read and write”, “Write only” and “Read only”.
- (Optional) Allow the user to specify which resources the key can access. This may be by naming or selecting resources.
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
The change to the API key is then “saved”.