vania-janet/multiturn-rag-retrieval-data huggingface dataset:
* How can I generate service credentials?

You can generate service credentials in the primary IBM Cloud IAM interface. When you select Use only IAM, service credentials include only IAM values. The service credential JSON looks like the following example:

{
"apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
"host": "2922d728-27c0-4c7f-aa80-1e59fbeb04d0-bluemix.cloudant.com",
"iam_apikey_description": "Auto generated apikey during resource-key [...]",
"iam_apikey_name": "auto-generated-apikey-050d21b5-5f[...]",
"iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Manager",
"iam_serviceid_crn": "crn:v1:staging:public:iam-identity::[...]",
"url": "https://76838001-b883-444d-90d0-46f89e942a15-bluemix.cloudant.com",
"username": "76838001-b883-444d-90d0-46f89e942a15-bluemix"
}

The values for the previous example are described in the following list:

apikey
: IAM API key.

host
: The DNS that resolves domain names with their corresponding IP addresses.

iam_apikey_description
: Description of IAM API key.

iam_apikey_name
: ID of IAM API key.

iam_role_crn
: The IAM role that the IAM API key has.

iam_serviceid_crn
To allow your IBM Cloud API key to create and manage other API keys dynamically, its associated service ID must have Editor platform access for the IAM Access Groups Service, and Operator platform access for the IAM Identity Service.

For step-by-step instructions to create an IBM Cloud API key with the correct level of access, switch to the UI or CLI steps.

The following example shows a query that you can use to configure a secrets engine for your instance. When you call the API, replace the API key variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X POST
--H "Authorization: Bearer {iam_token}" --H "Accept: application/json" --H "Content-Type: application/json" --d '{
"api_key": "2epu_ykv0PMp2MhxQmDMn7VzrkSlBwi6BOI8uthi_RCS", "config_type": "iam_credentials_configuration",
"name": "iam-configuration"
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

A successful response returns the ID value of the secret, along with other metadata. For more information about the required and optional request parameters, see [Create a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-secret).





 Configuring the IAM credentials engine with Terraform 

Before you can create dynamic IAM credentials, you must configure the IAM secrets engine for your service instance. You can configure a secrets engine programmatically by using Terraform for Secrets Manager.

The following example shows a configuration that you can use to configure the IAM credentials engine.

resource "ibm_sm_iam_credentials_configuration" "iam_credentials_configuration" {
instance_id = local.instance_id
region = local.region
name = "iam_credentials_config"
"resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
},
"iam_compatible": true,
"migrated": false,
"resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
"resource_alias_url": null
}
]
}



 Credential level access 

The access of the user must be equal to or greater than the access of the service credential. For example, if the credential has the IAM service role Writer, then the user that is trying to view the credential must have the IAM service role Writer or Manager for that particular service assigned. When a user doesn't have the correct access, details such as the API key value are redacted:

"credentials": {
"REDACTED": "REDACTED"
},





 IAM level access 

When the credential level access can't be determined by comparing the access of the user and the credential, the credential is redacted:

"credentials": {
"REDACTED": "REDACTED_EXPLICIT"
},

To view the credential, the user must have the IAM level access action resource-controller.credential.retrieve_all. This action is given with the Administrator role, and overrides any credential level access enabling the user to view the credential.
* Access to each service instance requires its own set of credentials.
* Uses HTTP basic authentication with credentials that aren't bound to an individual user or service.





* Why is the Use only IAM mode preferred?

The Use only IAM mode means that only IAM credentials are provided through service binding and credential generation. You gain the following advantages when you use IBM Cloud IAM:



* Managing access to IBM Cloudant with the standard tooling of IBM Cloud.
* Using credentials that you can easily revoke and rotate when you use IBM Cloud IAM.



For more information about the advantages and disadvantages between these modes, see [Advantages and disadvantages of the two access control mechanisms](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudantadvantages-and-disadvantages-of-the-two-access-control-mechanisms-ai).
* How can I create an instance by using the command line?

When you create a new IBM Cloudant instance from the command line, you must include the ibmcloud tool by using the -p parameter. This parameter enables or disables legacy credentials for an account by passing the option in JSON format. The option is called legacyCredentials.

To create an instance as Use only IAM, run the following command:

ibmcloud resource service-instance-create "Instance Name" 
cloudantnosqldb Standard us-south 
-p '{"legacyCredentials": false}'

If you don't use Use only IAM mode when you use the IAM Reader and Writer roles, you might grant users legacy credentials with more access permissions than you intended.
* How can I generate service credentials?

You can generate service credentials in the primary IBM Cloud IAM interface. When you select Use only IAM, service credentials include only IAM values. The service credential JSON looks like the following example:

{
"apikey": "MxVp86XHkU82Wc97tdvDF8qM8B0Xdit2RqR1mGfVXPWz",
In this case, you can choose to continue without selecting a role so that the new credential is created without an IAM Service role. This way, you can manage the fine-grained access by creating an IAM policy that you scope to a specific resource, like a bucket. To create the credential without an IAM service role, complete the following steps:



1. From the Resource list page, select the name of the service to open the service details page. Then, click Service credentials > New Credential+.
2. Provide a Name.
3. Select None as the role so that the new credential is created without an IAM Service role.
4. Next, go to Manage > Access (IAM) > Service IDs.
5. Select the service ID with the same name as the service credential key, and click Assign access.









 Adding a credential when binding an IAM-enabled service by using the API 

Services that are managed by IBM Cloud Identity and Access Management (IAM) can generate a resource key, also known as a credential. Credentials are service-specific and vary based on how each service defines the credentials they need to generate. A credential might contain a user name, password, host name, port, and a URL.

However, while the contents of each credential is unique to the service that generates it, all services managed by IAM require that new credentials include an IAM Service access role. Some services might generate more data that requires parameters to be passed in. For example, a service might require you to input a language parameter to set the default language that is returned in the resource key that is generated.

To create a resource key, call the [Resource Controller API](https://cloud.ibm.com/apidocs/resource-controller/resource-controllercreate-resource-key) as shown in the following example:



* Curl
* Java
* Python
* Go
* Node
To generate both a new service ID and API key for the secret, select an access group.

By selecting an access group from your IBM Cloud account, you determine the scope of access to assign to the service ID and the API key. The API key is dynamically generated and associated with your new IAM credential. This step ensures that your IAM credentials are scoped with the preferred level of permissions in your IBM Cloud account. You can assign up to 10 access groups.



If you used an existing service ID, the API key that was generated by Secrets Manager is automatically locked. If you selected an access group, both the new service ID and API key that Secrets Manager created for the secret are automatically locked. Each time you that [retrieve an IAM credentials secret](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-secrets&interface=apiget-secret-value-api) by using the API, the API key and the service ID that Secrets Manager generates are locked, even if you manually unlock them before retrieving the secret.







 Creating IAM credentials from the CLI 

To create a dynamic service ID and API key by using the Secrets Manager CLI plug-in, run the [ibmcloud secrets-manager secret-create](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-cli-plugin-secrets-manager-clisecrets-manager-cli-secret-create-command) command. For example, the following command creates an IAM secret with a lease duration of 12 hours.

ibmcloud secrets-manager secret-create
: Description of IAM API key.

iam_apikey_name
: ID of IAM API key.

iam_role_crn
: The IAM role that the IAM API key has.

iam_serviceid_crn
: The CRN of service ID.

url
: IBM Cloudant service URL.

username
: The internal IBM Cloudant account name.

For more information, see [IBM Cloud API keys and Use only IAM](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudantibm-cloudant-api-keys-and-use-only-iam_ai).





In most cases, rotating credentials is a straight-forward process:



1. Generate a replacement service credential. For more information, see [How can I generate service credentials?](https://cloud.ibm.com/docs?tab=faqsfind-service-credentials-iam).
2. Replace the current credential with the newly generated credential.
3. Delete the no-longer-used service credential.



However, when you rotate the credentials for a replication, if you are using legacy credentials in the replication document, the replication starts from the beginning. To ensure that changes arrive in a timely manner, we advise you to create a new replication once it catches up with deleting the previous replication and the associated service credential. The process is described in the following steps:



1. Generate a replacement service credential. For more information, see [How can I generate service credentials?](https://cloud.ibm.com/docs?tab=faqsfind-service-credentials-iam).
2. Create a replication with the same settings but new credentials.
3.
: Description of IAM API key.

iam_apikey_name
: ID of IAM API key.

iam_role_crn
: The IAM role that the IAM API key has.

iam_serviceid_crn
: The CRN of service ID.

url
: IBM Cloudant service URL.

username
: The internal IBM Cloudant account name.

For more information, see [IBM Cloud API keys and Use only IAM](https://cloud.ibm.com/docs/Cloudant?topic=Cloudant-managing-access-for-cloudantibm-cloudant-api-keys-and-use-only-iam_ai).





In most cases, rotating credentials is a straight-forward process:



1. Generate a replacement service credential. For more information, see [How can I generate service credentials?](https://cloud.ibm.com/docs/faqsfind-service-credentials-iam).
2. Replace the current credential with the newly generated credential.
3. Delete the no-longer-used service credential.



However, when you rotate the credentials for a replication, if you are using legacy credentials in the replication document, the replication starts from the beginning. To ensure that changes arrive in a timely manner, we advise you to create a new replication once it catches up with deleting the previous replication and the associated service credential. The process is described in the following steps:



1. Generate a replacement service credential. For more information, see [How can I generate service credentials?](https://cloud.ibm.com/docs/faqsfind-service-credentials-iam).
2. Create a replication with the same settings but new credentials.
3.
Optional: Add metadata to your secret or to a specific version of your secret.



1. Upload a file or enter the metadata and the version metadata in JSON format.



10. Click Next.
11. Set a lease duration or time-to-live (TTL) for the secret.

By setting a lease duration for your IAM credential, you determine how long its associated API key remains valid. After the IAM credential reaches the end of its lease, it is revoked automatically.

Minimum duration is 1 minute. Maximum is 90 days.
12. Optional: [Determine whether IAM credentials can be reused](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials&interface=uiiam-credentials-reuse-ui) for your secret.
13. Optional: Enable automatic rotation of your secret. Secrets can be automatically rotated only if the reuse IAM credentials option is selected.
14. Click Next.
15. [Determine the scope of access](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials&interface=uiiam-credentials-service-id-ui) to assign for your IAM credential.
16. Click Next.
17. Review the details of your secret.
18. Click Add.





 Reusing the same API key until the lease expires 

IAM credentials consist of a service ID and an API key. By default, the service ID and API key are single-use, ephemeral values that are generated and deleted each time that an IAM credentials secret is read or accessed.

If you'd like to continue to use those credentials through the end of the lease of your secret, you can set Reuse IAM credentials until lease expires to On. When you enable this option, your secret retains its current service ID, and API key values and reuses them on each read while the secret remains valid. After the secret reaches the end of its lease, the credentials are revoked automatically.
"labels":
"storage",
"us-south"
],
"last_update_date": "2020-12-15T14:31:42Z",
"name": "test-iam-credentials",
"secret_group_id": "432b91f1-ff6d-4b47-9f06-82debc236d90",
"secret_type": "IAM_CREDENTIALS",
"service_id": "ServiceId-0576925a-9651-4f3e-b8c7-ce1332324aa4",
"state": 1,
"state_description": "Active",
"ttl": 900
}
]
}

The response body shows the single-use api_key and service_id values that are generated for your secret. The ttl value indicates how long your credentials are valid (in seconds).
2. Export an environment variable with the newly generated API key.

Copy the api_key value that you generated in the previous step, and set it as an environment variable.

export API_key="<api_key>"







 Step 4: Use the API key to generate an access token 

By using the API key that you retrieved in the previous step, you can generate an IAM access token. The token is valid only for the duration that you initially defined for the IAM credential.

You can exchange the API key for an IAM access token by calling [IAM Identity Services API](https://cloud.ibm.com/apidocs/iam-identity-token-api). To generate an IAM token, run the following cURL command from your command line.
These credentials are used to determine infrastructure permissions, even if an [IBM Cloud IAM API key](https://cloud.ibm.com/docs/cli?topic=cli-kubernetes-service-clics_api_key_info) exists for the resource group and region. If the user whose credentials are stored does not have the required permissions to order infrastructure, then infrastructure-related actions, such as creating a cluster or reloading a worker node can fail.

You can't set multiple credentials for the same IBM Cloud Kubernetes Service resource group and region.

Before you use this command, make sure that the user whose credentials are used has the required [IBM Cloud Kubernetes Service and IBM Cloud infrastructure permissions](https://cloud.ibm.com/docs/containers?topic=containers-usersusers).

ibmcloud ks credential set classic --infrastructure-api-key API_KEY --infrastructure-username USERNAME --region REGION [-q]

Minimum required permissions
: Administrator platform access role for the cluster in IBM Cloud Kubernetes Service

Command options:

--infrastructure-username USERNAME
: Required: IBM Cloud infrastructure account API username. The infrastructure API username is not the same as the IBMid. To view the infrastructure API username, see [Managing classic infrastructure API keys](https://cloud.ibm.com/docs/account?topic=account-classic_keys).

--infrastructure-api-key API_KEY
: Required: IBM Cloud infrastructure account API key. To view or generate an infrastructure API key, see [Managing classic infrastructure API keys](https://cloud.ibm.com/docs/account?topic=account-classic_keys).

--region REGION
: Specify a region in IBM Cloud Kubernetes Service: jp-osa, jp-tok, au-syd, eu-de, eu-gb, us-east, or us-south.

-q
: Optional: Do not show the message of the day or update reminders.



 Example credential set classic command
For auditing purposes, the service retains the metadata of up to 50 versions for each secret, which you can review as part of a secret's [version history](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history).



 Supported secret types 

Restoring to a previous version is supported for [IAM credentials](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-iam-credentials) and [public certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-public-certificates).







 Restoring a previous version with the API 

You can use the Secrets Manager API to restore a secret to its previous version.

The following example request restores the previous version of a secret. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance. Allowable values for {secret_type} are: iam_credentials, public_cert

To list the versions of a secret and obtain the ID of each version, use the [List versions API](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-version-history&interface=apiversions-api).

curl -X POST
--H "Authorization: Bearer {iam_token}" --H "Accept: application/json" --H "Content-Type: application/json" --d '{
"restore_from_version": "previous",
"custom_metadata": {
"metadata_custom_key": "metadata_custom_value"
},
"version_custom_metadata": {
"custom_version_key": "custom_version_value"
}
}' 
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

Currently, you can restore only one version back for IAM credentials and public certificate secrets.
Why am I blocked from ordering a public certificate or generating IAM credentials? 

You try to use IBM Cloud® Secrets Manager to order public certificates or generate IAM credentials, but the service is unable to complete the action.

  What’s happening 

You're working in an IBM Cloud account that has [IP address access restrictions](https://cloud.ibm.com/docs/account?topic=account-ips). When you try to use a feature in Secrets Manager that requires a user-provided IBM Cloud API key, for example when you generate IAM credentials, you encounter an error similar to the following examples:

IAM credentials couldn't be regenerated because IP address restrictions are enabled for the account. Update the IP address settings in your account to include IP addresses for Secrets Manager and try again.

Cloud Internet Services (CIS) couldn't be reached because IP address restrictions are enabled for the account. Update the IP address settings in your account to include IP addresses for Secrets Manager and try again.

  Why it’s happening 

These errors can occur when Secrets Manager attempts to log in to the target account with the configured API key in order to complete the request. However, the service is unable to do so because the account allows access to specific IP addresses only. To allow the account to accept requests from Secrets Manager, you must specify an allowlist of IP addresses, along with your own IP address.

  How to fix it 

To resolve the issue, ensure that the IP address restriction settings in the account are updated to allow the IP addresses that correspond with the region in which your Secrets Manager is located.



1.  In the IBM Cloud console, click Manage > Access (IAM), and select Settings.
2.  From the Account restrictions section, edit the IP address access setting.
3.  In the Allowed IP addresses field, include the allowlist of IP addresses that you defined based on the locations where access requests originate. For more information, see [Managing access with context-based restrictions](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-access-control-cbr).
This API now supports arbitrary, iam_credentials, and username_password secrets, in addition to public_cert and imported_cert.







 20 September 2021 

This release includes the following updates:



* Added public_cert secret type that can be used to order domain-validated TLS certificates with the service. For more information, see [Ordering certificates](https://cloud.ibm.com/docs/secrets-manager?topic=secrets-manager-public-certificatesorder-public-certificates).
* Added the [Add a configuration](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2create-config-element), [List configurations](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-config-elements), [Update a configuration](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2update-config-element), [Get a configuration](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-config-element), and [Remove a configuration](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2delete-config-element) methods that can be used to add engine configurations to the service. Currently, these APIs support public_cert secrets only.
* Updated the [Get a version of a secret](https://cloud.ibm.com/apidocs/secrets-manager/secrets-manager-v2get-secret-version) method that can be used to retrieve the previous version of a secret. This API now supports public_cert secrets in addition to imported_cert.







 11 July 2021 

This release includes the following updates:



* Changed the maximum length for secret names to 240 characters.
* Changed the maximum length for secret descriptions to 1024 characters.







 20 June 2021 

This release includes the following updates:



* Added imported_cert secret type that can be used to store X.509 certificates in the service.
Get the configuration of a secret type 

Retrieves the configuration of a secrets engine.



 Example request 

Get the configuration of iam_credentials secrets engine.

curl -X GET "https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/iam_credentials/config/root" -H 'X-Vault-Token: {Vault-Token}'





 Example response 

A request to get the configuration of the iam_credentials secrets engine returns the following response:

{
"request_id": "12f0a38d-93a5-6a9a-1997-79928f15c5ea",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"api_key_hash": "caf9eabec3c6dcc7f91cb6ea295eb97c8e34e70b0cf5942d6351d8746d9cc2da"
},
"wrap_info": null,
"warnings": null,
"auth": null
}







 Add a configuration 

Adds a configuration element to a secrets engine. This method is used for more complex engines, for example the public_cert and private_cert engines.

You can add multiple configurations for your instance:



* Up to 10 public certificate authority configurations
* Up to 10 DNS provider configurations
* Up to 10 private root certificate authority configurations
* Up to 10 private intermediate certificate authority configurations
* Up to 10 certificate templates



Public CAs

DNS providers

Private CAs



Table 11. Public certificates engine request parameters

 Request parameters Description 

 name A human-readable name to assign to your certificate authority configuration. 
 type The environment type, for example the Let's Encrypt staging or production environment that corresponds with the URL that you want to target to order public certificates. Allowable values are: letsencrypt-stage, letsencrypt