IBM Cloud Docs
Using an API key with Secrets Manager to authorize a project to deploy an architecture

Using an API key with Secrets Manager to authorize a project to deploy an architecture

When you configure your deployable architecture, you are required to select an authentication method. You can use an API key that is stored as a secret to authorize a project to deploy in an account.

A secret is a piece of sensitive information, for example an API key, password, or any type of credential that you might use to access a confidential system. You can use a secret in IBM Cloud® Secrets Manager as a way to manage API keys dynamically and store them securely in your own dedicated instance.

Though it is possible to add your API key directly into your configuration, it is not recommended, as the API key displays in your project.json file and is visible to anyone who exports it.

Before you begin

  1. Make sure that you are assigned the required permissions to create the project tooling resources within the account in addition to permission to create projects:

    • The Editor role on the IBM Cloud Projects service.
    • The Editor and Manager role on the IBM Cloud® Schematics service.
    • The Viewer role on the resource group for the project.

    For more information about access and permissions, see Assigning users access to projects.

  2. Each API key that you create has the same access that you are assigned as a user. Before you create an API key, make sure that you have access to deploy architectures in the account that you want to deploy to, also known as your target account. If you have the following wide-ranging access, then you can deploy architectures in the account:

    • The Administrator role for All Identity and Access enabled services.
    • The Administrator role for All Account Management services.

    Alternatively, you can create an API key that is associated with a service ID. Service ID API keys inherit all access that is assigned to the specific service ID. So, you can scope the access for the service ID to the minimum that is required for the deployable architecture that you're configuring. This approach is similar to using a trusted profile with specific access based on the deployable architecture. For more information on finding the required access roles for any given deployable architecture, see granting specific access based on the deployable architecture.

  3. Complete the required steps to create a project and add a deployable architecture. You authorize the project to deploy with an API key or existing secret when you configure your deployable architecture.

Creating an API key

Complete the following steps to create an API key:

  1. In the IBM Cloud console, sign in to the account that you want to deploy to.

  2. Go to Manage > Access (IAM) > API keys.

  3. Click Create an IBM Cloud API key.

  4. Enter a name and description for your API key.

  5. Click Create.

  6. Then, click Show to display the API key. Or, click Copy to copy and save it for later, or click Download.

    For security reasons, the API key is only available to be copied or downloaded at the time of creation. If the API key is lost, you must create a new API key.

Adding an API key to Secrets Manager

After you create an API key, complete the following steps to add it to Secrets Manager in the account that contains your project:

  1. Create a Secrets Manager service instance in your IBM Cloud account. To create a secret, you must have the Writer role or higher on the Secrets Manager service.
  2. After you create your secret instance, make sure that you select Other secret type to add an arbitrary secret. For information about creating an arbitrary secret, see Creating arbitrary secrets in the UI. Your arbitrary secret must contain the API key. The API key must be created in the target account that you want to deploy to.

Using an existing secret

After you added your API key to Secrets Manager as an arbitrary secret, you can use that secret to authorize your project to deploy. Complete the following steps:

  1. In the IBM Cloud console, sign in to the account that you want to deploy the project to.
  2. Go to Menu Menu icon > Projects.
  3. Select the project that includes the deployable architecture configuration that you want to authorize.
  4. From the Configurations tab, select the configuration.
  5. Click the Actions icon Actions icon > Edit
  6. In the required input section, go to the Authentication method. Make sure that Use an existing secret is set to Yes.
  7. Select API key using Secrets Manager.
  8. Click Select from Secrets Manager.
  9. Choose the service instance, secret group, and secret.
  10. Click Save.

During the configuration process, you might decide to add the API key directly for experimental work. This option is not recommended, especially for deployments to your production account, because the API key displays in your project.json file and is visible to anyone who exports it.