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

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 a secret reference

After you create a secret, you can use that secret as a reference to authorize your project to deploy. For more information about references, see Referencing values. To configure your deployable architecture with a secret reference, 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 > 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 Edit
6. In the Configure section, hover over the API key field, and select the Key icon.
7. Choose the service instance and select the secret that you want to use and click OK.

You can also use a trusted profile as a reference. In the Configure section, for the method, select Trusted profile and enter your trusted profile ID. For more information, see Using trusted profiles.