vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Understanding API keys 

An application programming interface key (API key) is a unique code that is passed in to an API to identify the calling application or user. API keys are used to track and control how the API is being used, for example to prevent malicious use or abuse of the API. The API key often acts as both a unique identifier and a secret token for authentication, and is assigned a set of access that is specific to the identity that is associated with it.

To view your API keys, go to Manage > Access (IAM) > API keys in the IBM Cloud console.



 IBM Cloud API keys for users 

IBM Cloud® API keys are associated with a user's identity, and each API key that is created by the user has the same access that the user is assigned. The access that the user is assigned can be from policies across multiple accounts that the user is a member of. Therefore, it is possible that a user's API key can be used to generate a token and access resources that a user has access to outside of the account where the API key was created.

The user API key can be used directly or used to generate a token. Because users can be members of multiple accounts and have access to many resources across multiple accounts, and the API key is used to identify the user, it can provide the ability to gain access to almost any resource, in any account, that the user has access to. For this reason, the user API key should be treated similar to a username and password and should never be shared.

IBM Cloud API keys for users can be created and associated with a functional ID. A functional ID is a user ID created to represent a program, application, or service. The functional ID can be invited to an account and assigned only the access for a particular purpose, such as interacting with a specific resource or application. The functional ID should be granted only the minimum level access in a single account that is needed for the specific function which it was created.

If a service requires a user API key for interacting with other services or applications, use the functional ID user API key. By using the API key that is associated with the functional ID, you can provide only the access that is needed for that service.
The second diagram shows a policy that is scoped to an account group that provides access to manage only that account group and the child accounts that are organized within it.

Zoom

![Enterprise access](https://cloud.ibm.com/docs-content/v1/content/d4595e5202a9a27767cf034e81b038cdf772e0d5/secure-enterprise/images/enterprise-access.svg)

Figure 1. Diagram for enterprise access

The target and role of the policy is important in determining the scope of access. A user, service ID, or access group in an enterprise can complete enterprise management tasks:



* Across the entire enterprise.
* On an account group that might contain other account groups and accounts.
* On a single account.



For example, a user can complete tasks within an account group if they're assigned an access policy on the Enterprise account management service with a target that is scoped to a specific account group. The user can't complete actions that affect the enterprise as a whole, like updating the enterprise name or domain, when the target is set to a specific account group or account.

You can assign users in a child account in the enterprise access policies that apply to the management of only that account or the resources that it contains. For example, if you assign a user in a child account a role on the Enterprise account management service, the user can't take actions at the enterprise account level. You must add them to the enterprise account and assign the policy in that context.

Zoom

![Account access](https://cloud.ibm.com/docs-content/v1/content/d4595e5202a9a27767cf034e81b038cdf772e0d5/secure-enterprise/images/account-access.svg)

Figure 2. Diagram for account access



 Required policies for specific jobs 

Depending on the job that needs to be done, a combination of access policies might be required for a user who is not the owner of the enterprise.
* An IAM policy with minimum platform role Administrator and service role Manager for the COS service: The administrator role is required to define the service ID, with its associated API key, that is used by the IBM Cloud Activity Tracker instance to authenticate and access the IBM Cloud Object Storage instance. The manager role is required to create and configure a bucket.



You also need a service ID. A service ID identifies a service similar to how a user ID identifies a user. Service IDs are not tied to a specific user. If the user that creates the service ID leaves your organization and is deleted from the account, the service ID remains. The IBM Cloud Activity Tracker service uses an API key that is associated to a service ID that you define on your COS instance to authenticate and write files to the COS bucket.

Create a service ID for for the COS instance with writer permissions. Restrict access to the service ID so that the API key that is associated to it can only write to the bucket that you configure for archiving.

If you add PII information in the name or the description of the service ID, you might be disclosing sensitive data to others in the same account.

When you define your service ID name, do not add sensitive information in the name or in the description.

You might have a requirement to rotate API keys regularly or your API key might be compromised.

Rotate the API key that is associated with your service ID regularly to prevent any security breaches caused by leaked keys or to comply with security guidelines.





 IAM policies to control access to the archived files 

In COS, you can define policies to control the permissions that are granted to service IDs and users to read, write, update object properties, and delete objects. [Learn more](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam).

Restrict user access to archived files in the bucket.





 EU supported account 

When you archive logs from the Frankfurt auditing instance to an IBM Cloud Object Storage (COS) bucket, consider the following information:



* When you provision an instance of the COS service, this instance is a global one in your account. It is not region bound.
* An IAM policy with minimum platform role Administrator and service role Manager for the COS service: The administrator role is required to define the service ID, with its associated API key, that is used by the IBM Log Analysis instance to authenticate and access the IBM Cloud Object Storage instance. The manager role is required to create and configure a bucket.



You also need a service ID. A service ID identifies a service similar to how a user ID identifies a user. Service IDs are not tied to a specific user. If the user that creates the service ID leaves your organization and is deleted from the account, the service ID remains. The IBM Log Analysis service uses an API key that is associated to a service ID that you define on your COS instance to authenticate and write files to the COS bucket.

Create a service ID for for the COS instance with writer permissions. Restrict access to the service ID so that the API key that is associated to it can only write to the bucket that you configure in logging for archiving.

If you add PII information in the name or the description of the service ID, you might be disclosing sensitive data to others in the same account.

When you define your service ID name, do not add sensitive information in the name or in the description.

You might have a requirement to rotate API keys regularly or your API key might be compromised.

Rotate the API key that is associated with your service ID regularly to prevent any security breaches caused by leaked keys or to comply with security guidelines.





 IAM policies to control access to the archived files 

In COS, you can define policies to control the permissions that are granted to service IDs and users to read, write, update object properties, and delete objects. [Learn more](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-iam).

You will want to restrict user access to archived files in the bucket.





 EU supported account 

When you archive logs from the Frankfurt logging instance to an IBM Cloud Object Storage (COS) bucket, consider the following information:



* When you provision an instance of the COS service, this instance is a global one in your account. It is not region bound.
The user starts the sequence by visiting an account-specific URL with their browser. This is either https://cloud.ibm.com/authorize/<account id> or https://cloud.ibm.com/authorize/<account alias>. The account alias can be configured on the IAM Identity provider configuration pages in the IBM Cloud console.

Using a specific URL is required to address the correct federated SAML partner.
2. The IBM Cloud console (console) redirects the user's browser to IBM Cloud's IAM component. As part of the redirect, the account ID or alias is sent to IAM.
3. With the help of the account ID or alias, IAM determines the App ID instance that is needed to run the login sequence. Therefore, IAM sends back a redirect request to the user's browser.
4. The browser completes the redirect and ends on an App ID provided page. This page immediately returns a redirect to the browser containing a SAML request.
5. The SAML request is sent to the enterprise customer's user authentication and authorization system.
6. After validating the user's credentials, the enterprise customer's system sends a redirect instruction to the user's browser. Part of this redirect is the SAML response containing assertions that describe the user and the additional attributes of that user.
7. The browser completes the redirect and sends the SAML response with assertions to the App ID instance.
8. After validating the SAML response, App ID now sends a redirect to the browser that contains an authorization code to continue the authentication flow according to the OpenID Connect standard.
9. The browser contacts IAM and provides the authorization code so that IAM can retrieve the required tokens from App ID using the OpenID Connect standard.
10. After App ID has provided the required tokens, IAM is now finishing its authentication flow with the console by sending an OAuth2 compliant redirect with an authorization code to the browser.
11.
* To configure service binding access for all service instances in all resource groups:

ibmcloud ce project update --binding-resource-group ""



When you run the project update command, a service ID is created for the project, and is used to configure the current project for service bindings. If you do not have permission to create this service ID, then you receive an error that your project is not ready to work with service bindings. Talk to your account administrator about your access policies, or ask the administrator to [configure access for Code Engine to automatically create and manage the service ID for service bindings](https://cloud.ibm.com/docs/codeengine?topic=codeengine-configure-bindaccessbind-auto-servid-access).









 Using a custom service ID for service bindings 

If you want more control over access policies or resource groups, you can create a custom service ID for your service instance.

Your organization might choose to use a custom service ID for accessing a specific service instance if the account owner doesn't want to grant Administrator access for a user to the All Identity and Access enabled services within a resource group, which is required for Code Engine to automatically create and manage the service ID for service bindings. The account owner might want to scope the user access to a specific service type or service instance. In these cases, a custom service ID provides this control.

To use a custom service ID for service bindings,



* [Create a custom service ID with access permissions for Code Engine service bindings](https://cloud.ibm.com/docs/codeengine?topic=codeengine-configure-bindaccessbind-auto-servid-access-custom).
* [Configure your project to use the custom service ID](https://cloud.ibm.com/docs/codeengine?topic=codeengine-configure-bindaccessbind-custom-servid-project).





 Creating a custom service ID with access permissions for Code Engine service bindings
Manage user access to virtualized table.



 ibmcloud watson-query virtualized-table-user-grant 

Grant a user access to a specific virtualized table.

ibmcloud watson-query virtualized-table-user-grant --table-name TABLE-NAME --table-schema TABLE-SCHEMA --user USER



 Command options 

--table-name (string)
: The name of the virtualized table. Required. The minimum length is 1 character.

--table-schema (string)
: The schema of the virtualized table. Required. The minimum length is 1 character.

--user (string)
: The identifier of the authorization, if grant access to all users, the value is PUBLIC, othervise the value is the watson query username. Required. The minimum length is 1 character.





 Examples 

Grant a user access to a specific virtualized table

ibmcloud watson-query virtualized-table-user-grant --table-name TABLE1 --table-schema DV_IBMID_270001PD8Q --user user1@ibm.com







 ibmcloud watson-query virtualized-table-user-revoke 

Revoke user access to the virtualized table.

ibmcloud watson-query virtualized-table-user-revoke --user USER --table-name TABLE-NAME --table-schema TABLE-SCHEMA



 Command options 

--user (string)
: The watson query user name, if the value is PUBLIC, it means revoke access privilege from all watson query users. Required.

--table-name (string)
: The virtualized table's name. Required.

--table-schema (string)
: The virtualized table's schema name. Required.





 Examples 

Revoke user access to the virtualized table

ibmcloud watson-query virtualized-table-user-revoke --table-name TABLE1 --table-schema DV_IBMID_270001PD8Q --user user1@ibm.com









 Roles
For more information, see [Use storage classes](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-classes).

Note: It is not possible to change the storage class of a bucket once the bucket is created. If objects need to be reclassified, it is necessary to move the data to another bucket with the wanted storage class.
7. Optionally, add a Key Protect Key to encrypt data at rest.

All objects are encrypted by default by using randomly generated keys and an all-or-nothing-transform. While this default encryption model provides at-rest security, some workloads need to be in possession of the encryption keys used. For more information, see [Manage encryption](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-encryption).







 Step 4. Create a service ID for the IBM Cloud Object Storage instance 

A service ID identifies a service similar to how a user ID identifies a user. Service IDs are not tied to a specific user. If the user that creates the service ID leaves your organization and is deleted from the account, the service ID remains.

You must create a service ID for your IBM Cloud Object Storage instance. This service ID is used by the IBM Log Analysis instance to authenticate with your IBM Cloud Object Storage instance.

You must assign specific access policies to the service ID that restrict permissions for using specific services, or even combine permissions for accessing different services. For example, to restrict access to a single bucket, ensure that the service ID doesn't have any instance level policies by using either the console or CLI.

Complete the following steps to create a service ID with writing permissions for the IBM Cloud Object Storage instance:



1. Log in to your IBM Cloud account.

Click [IBM Cloud dashboard](https://cloud.ibm.com/login) to launch the IBM Cloud dashboard.

After you log in with your user ID and password, the IBM Cloud Dashboard opens.
2. From the Dashboard, select the IBM Cloud Object Storage instance where you plan to create the bucket.
3. Select Service credentials.
Note that IAM is a global service, but the custom resources (assistants and skills) used by Watson Assistant access control means each region, which has specific resources, requires specific policies.

For an active/passive topology, some form of a [circuit break pattern](https://martinfowler.com/bliki/CircuitBreaker.html) can be used. A single service instance in a given region is used exclusively unless errors are detected. At that point, the system can respond by updating the relevant failover metadata to route traffic to the service instance in the other region. Once a failover happens, you can decide to continue using the new region as the active instance, or if you want to resume using the initial region once it has stabilized.

For an active/active topology, some form of a load balancing can be used, where two or more service instances in unique regions always receive a percentage of traffic. Additional logic would need to be established to determine when to pull a region out of rotation. This monitoring logic could use a [circuit break pattern](https://martinfowler.com/bliki/CircuitBreaker.html) similar to the active/passive configuration or rely on a separate dedicated monitoring framework that determines region health. Also similar to active/passive, determining when to insert a region back in rotation would need to be considered as well.





 Failover for v2 stateful API 

Failover for the v2 stateful API is similar to stateless, with these details to consider:



* The state of a given conversation is persisted by Watson Assistant in a database that is tied to a particular region. As such, a failover for the stateful v2 /message may more disruptive.
* For an active/passive topology, you should assume that all in-progress conversations are ended.
* For an active/active topology, given the region-locked persistence constraints of the v2 stateful /message architecture, all turns (/message API calls) of a given conversation (session) should occur within the same region.
Get information about a specific preset GET <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 
 Modify an existing preset PUT <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 
 Delete a preset DELETE <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 



Where <PRESET_ID> is the ID of a preset.





 Endpoint URL 

Depending on [your account settings](https://cloud.ibm.com/docs/account?topic=account-service-endpoints-overview), you can use public or private endpoints to manage presets programmatically. For information about endpoints for each region, see [API endpoints](https://cloud.ibm.com/docs/log-analysis?topic=log-analysis-endpointsendpoints_api).





 Authentication 

When you manage presets programmatically, you must use a service key. Authorization to the Configuration API is enforced by using a service key.

A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a logging instance. For more information on how to generate a service key, see [Managing service keys](https://cloud.ibm.com/docs/log-analysis?topic=log-analysis-service_keys).

Use of the Configuration REST API is done by adding a valid service key to the HTTP Authorization request header. You must pass the service key as a header parameter (-H) on your requests.

For example, in a cURL request, you must set the servicekey header as follows:

-H "servicekey: <SERVICE_KEY>"





 Body parameters 

The following fields are body parameters that you can set in the API request:



 name (string) 

Specifies the name of the view.

The following table indicates when the name parameter is required:



Table 2. Required status per method

 Action Request Field required 

 Create a preset POST !
Get information about a specific preset GET <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 
 Modify an existing preset PUT <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 
 Delete a preset DELETE <ENDPOINT>/v1/config/presetalert/<PRESET_ID> 



Where <PRESET_ID> is the ID of a preset.





 Endpoint URL 

Depending on [your account settings](https://cloud.ibm.com/docs/account?topic=account-service-endpoints-overview), you can use public or private endpoints to manage presets programmatically. For information about endpoints for each region, see [API endpoints](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-endpointsendpoints_api).





 Authentication 

When you manage presets programmatically, you must use a service key. Authorization to the Configuration API is enforced by using a service key.

A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to an auditing instance. For more information on how to generate a service key, see [Managing service keys](https://cloud.ibm.com/docs/activity-tracker?topic=activity-tracker-service_keys).

Use of the Configuration REST API is done by adding a valid service key to the HTTP Authorization request header. You must pass the service key as a header parameter (-H) on your requests.

For example, in a cURL request, you must set the servicekey header as follows:

-H "servicekey: <SERVICE_KEY>"





 Body parameters 

The following fields are body parameters that you can set in the API request:



 name (string) 

Specifies the name of the view.

The following table indicates when the name parameter is required:



Table 2. Required status per method

 Action Request Field required 

 Create a preset POST !
This means that any access that is assigned to the ID by its membership in an access group is removed when the service ID is removed from the access group.



 Providing user access for locking service IDs 

In order for a user to have access to lock and unlock service IDs and API keys that are associated with service IDs, they must be assigned a specific access policy. Two types of access policies can grant the proper access: access to all service IDs in the account or access to a specific service ID in the account

To assign access to all service IDs in the account, set an access policy for account management services with the following details:



* Editor or Administrator role
* IAM Identity Service



To assign access to a specific service ID in the account, set an access policy for account management services with the following details:



* Editor or Administrator role
* IAM Identity Service
* Specify "serviceid" in the Resource type field
* Specify the service ID identifier in the Resource ID field



To get the identifier of a specific service ID, go to Manage > Access (IAM) in the IBM Cloud console, and select Service IDs. Select the service ID that you want to view details for, and copy the ID value.





 Locking a service ID from the UI 

A locked service ID is indicated by the Locked icon ![Locked icon](https://cloud.ibm.com/docs-content/v1/content/4d8c6eec891cff72b666dc24bd3211810c77fb42/account/images/locked.svg).



1. In the IBM Cloud console, click Manage > Access (IAM) and then select Service IDs.
2. Identify the row of the service ID that you want to lock, and click the Actions icon ![Actions icon](https://cloud.ibm.com/docs-content/v1/content/4d8c6eec891cff72b666dc24bd3211810c77fb42/icons/action-menu-icon.svg) > Lock service ID.