Setting up the API

IBM Cloud Satellite shares the same application programming interface (API) as IBM Cloud Kubernetes Service and Red Hat OpenShift on IBM Cloud, so that you can use the same methods to consistently create and manage your Satellite resources.

About the API

The Satellite API automates the provisioning and management of IBM Cloud infrastructure resources for your clusters so that your apps have the compute, networking, and storage resources that they need to serve your users.

The API supports the different infrastructure providers that are available for you to create clusters and resources. The v2 API is designed to avoid breaking existing functionality when possible. However, make sure that you review the following differences between the v1 and v2 API.

API endpoint prefix: v1 API: https://containers.cloud.ibm.com/global/v1; v2 API: https://containers.cloud.ibm.com/global/v2
API reference docs: v1 API: https://cloud.ibm.com/apidocs/kubernetes/containers-v1-v2; v2 API: https://cloud.ibm.com/apidocs/kubernetes/containers-v1-v2
API architectural style: v1 API: Representational state transfer (REST) that focuses on resources that you interact with through HTTP methods such as GET, POST, PUT, PATCH, and DELETE.; v2 API: Remote procedure calls (RPC) that focus on actions through only GET and POST HTTP methods.
GET responses: v1 API: The GET method for a collection of resources (such as GET v1/clusters) returns the same details for each resource in the list as a GET method for an individual resource (such as GET v1/clusters/{idOrName}).; v2 API: To return responses faster, the v2 GET method for a collection of resources (such as GET v2/clusters) returns only a subset of information that is detailed in a GET method for an individual resource (such as GET v2/clusters/{idOrName}). Some list responses include a providers property to identify whether the returned item applies to classic or VPC infrastructure. For example, the GET zones list returns some results such as mon01 that are available only in the classic infrastructure provider, while other results such as us-south-01 are available only in the VPC infrastructure provider.
Cluster, worker node, and worker-pool responses: v1 API: Responses include only information that is specific to the classic infrastructure provider, such as the VLANs in GET cluster and worker responses.; v2 API: The information that is returned varies depending on the infrastructure provider. For such provider-specific responses, you can specify the provider in your request. For example, VPC clusters don't return VLAN information since they don't have VLANs. Instead, they return subnet and CIDR network information.

Working with API keys

To manage the IBM Cloud API keys that are associated with your user identity or the ones that you have access to manage for other users in the account, go to Manage > Access (IAM) > API keys in the IBM Cloud console.

On the IBM Cloud API keys page, you can create, edit, or delete your own IBM Cloud API keys. You can also manage all classic infrastructure API keys for users in your user hierarchy. If you are the account owner or a user with the required access to manage other user's API keys in the account, you can use the View filter to list and manage those API keys.

API key expiration

When an API key is created or updated, you can set an expiration date. If an expiration date is specified, the API key is invalid after that date. Expired API keys are automatically deleted 90 days after they expire. A few days before an API key expires, a notification is sent through the IBM Cloud notification service to the user who owns the API key (for user-level keys) or to the account owner (for service ID API keys).

Leaked API key protection

API keys are powerful credentials that provide access to your IBM Cloud resources and services. When these keys are inadvertently exposed in public repositories, logs, or other locations, they can create significant security risks. Bad actors actively scan public repositories for leaked credentials and can quickly exploit them for unauthorized access, crypto mining operations, or other malicious activities—often within minutes of exposure. Depending on the access granted to the user or service ID associated with the key, bad actors may be able to:

Access or delete data.
Provision resources in your account, including resources that may be used for bitcoin mining.
Perform other actions in the services in your account.
Create additional IDs or API keys within your account to give themselves persistent access - even after you rotate the compromised key.

IBM Cloud leverages secret-scanning capabilities from platforms like GitHub and GitLab to help identify exposed API keys. When a key is determined to have been leaked, you or your security team can quickly take the appropriate action based on the disposition you configured for that key. Depending on your configuration, IBM can take the following actions:

Disable the leaked key: The API key is immediately disabled by IBM, preventing unauthorized use while you investigate and determine next steps. This approach is recommended for most keys except in situations where an assessment has been done and the risk due to an exposed key is low. If a key is disabled, your application's API calls to cloud services will fail, which could potentially cause an outage.
Delete the leaked key: The API key is permanently deleted by IBM upon detection. This provides the strongest protection but requires creating a new key. If a key is deleted, your application's API calls to cloud services will fail, which could potentially cause an outage.
Do nothing: No automatic action is taken. You might still receive notifications about the exposure, but must manually address the issue.

Before you make a decision, it is important to weigh the security consequences of a key exposure against the consequences of an application outage. IBM recommends using the "Disable" option for most keys except in situations where an assessment has been done and the risk if a key were exposed is low due to limited access. If your organization requires the "Do nothing" setting for specific API keys due to production requirements, IBM encourages you regularly analyze your security posture, implement compensating controls such as frequent key rotation and plan to enable automatic protection when your environment allows.

For more information, see Reviewing leaked user API keys or Reviewing leaked service ID API keys.

Generating an IAM token

You can generate an IAM token by using either your IBM Cloud API key or a service ID's API key. The API key is a permanent credential that can be reused if you don't lose the API key value or delete the API key in the account. This process is also used if you are developing an application that needs to work with other IBM Cloud services. You must use a service ID API key to get an access token to be passed to each of the IBM Cloud services.

An access token is a temporary credential that expires after 1 hour at the latest. After the acquired token expires, you must generate a new token to continue calling IBM Cloud or service APIs, and you can perform only actions that are allowed by your level of assigned access within all accounts. Use the response property expires_in in the API response to identify the length of time that your specific access token is valid.

Passing an IBM Cloud IAM token to authenticate with a service's API

To retrieve an IAM access token, the API client must first invoke an IBM Cloud IAM API to authenticate and retrieve that token. The preferred way for IBM Cloud service API clients is to use an IBM Cloud API key to get an IAM access token. The IAM access token, which was implemented as a JSON Web Token, can be used for multiple invocations of IBM Cloud services that accept IAM access tokens as an authentication method. As IAM access tokens are digitally signed with asymmetric keys, IBM Cloud services can validate an IAM access token without invoking any external service. This dramatically improves the performance of invoking an API.

Authenticating with a service API by using an access token — Retrieving a token from IAM by using an API key and passing the access token to target services to validate credentials

To authenticate with a service's API by using an access token, complete the following steps:

First, create an IBM Cloud API key if you have not already.
The next step for the API client is the retrieval of an IAM access token, as described in Getting an IAM token from an API key.
From the response, extract the property access_token to get the IAM access token. expires_in indicates the seconds until the IAM access token access_token expires. Either use this relative value or the absolute time stamp expiration based in UNIX time.
Send the IAM access token as described in RFC 6750, section 2.1. Authorization Request Header Field.

Review the following example:

Use the HTTP header Authorization
Prefix the IAM access token with the literal Bearer eyJhbGciOiJSUzI1Ng...
Add the prefixed IAM access token to the HTTP header: Authorization: Bearer eyJhbGciOiJSUzI1Ng...

curl -H "Authorization: Bearer eyJhbGciOiJSUzI1Ng..."

import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
String bearerToken = // ... obtain bearer token value ...

// Create the authenticator.
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator(bearerToken);

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken = // ... obtain new bearer token value
authenticator.setBearerToken(newToken);

const ExampleServiceV1 = require('mysdk/example-service/v1');
const { BearerTokenAuthenticator } = require('mysdk/auth');

const authenticator = new BearerTokenAuthenticator({
  bearerToken: '<access-token>',
});

const myService = new ExampleServiceV1({
  authenticator,
});
...

// Later when the access token expires, the application must acquire
// a new access token, then set it on the authenticator.
// Subsequent request invocations will include the new access token.
authenticator.setBearerToken('<new-access-token>')

from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator

authenticator = BearerTokenAuthenticator(<your_bearer_token>)
service = ExampleService(authenticator=authenticator)

# after getting a new access token...
service.get_authenticator().set_bearer_token('54321');

    import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
bearerToken := // ... obtain bearer token value ...
authenticator := &core.BearerTokenAuthenticator{
    BearerToken: bearerToken,
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.
...
// Later, if your bearer token value expires, you can set a new one like this:
newToken := // ... obtain new bearer token value
authenticator.BearerToken = newToken

Use the same IAM access token for subsequent IBM Cloud service API calls to achieve the best performance and scalability.

Passing an IBM Cloud API key to authenticate with a service API

API clients can directly pass an IBM Cloud API key to the target service’s API. To do so, send the apikey keyword as the user name and the IBM Cloud API key as the password by using basic authorization HTTP header to the target service.

It is recommended that in all cases of passing an API key to a service API that you use an API key for a service ID or a user API key that is associated with a functional ID that is assigned only the level of access required to work with the particular service.

The target service API must introspect the IBM Cloud API key by using the IBM Cloud IAM service. The following graphic shows three API interactions. The IBM Cloud API key is passed to every target service’s API, so each target service must look up the IBM Cloud API key details by invoking IBM Cloud IAM.

Authenticating with a service API by using an API key — Passing API keys to target services which then pass the API key to IAM to validate credentials

Using an IBM Cloud API key is convenient, and it makes it easy to discover new APIs and quickly try out prototypes. This method requires you to send the IBM Cloud API key to the target service‘s API in a readable format, which unnecessarily compromises the API key. Additionally, as the target service’s API must always introspect the API key, this method is less performant and therefore not recommended for production work loads.

To authenticate with a service's API by using an API key, complete the following steps:

First, create an IBM Cloud API key if you have not already.
Send the IBM Cloud API key as defined in RFC 7617 as HTTP header “Authorization”. Use apikey as the user name, and the API key value as the password.

As an example, the following steps assume that the API key is 0a1A2b3B4c5C6d7D8e9E:

Concatenate the user name apikey and the API key that is separated by a colon: apikey:0a1A2b3B4c5C6d7D8e9E
Base64 encode the string: base64("apikey:0a1A2b3B4c5C6d7D8e9E") => YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF
Set the HTTP header Authorization with schema Basic, for example Authorization: Basic YXBpa2V5OjBhMUEyYjNCNGM1QzZkN0Q4ZTlF. When you use the curl command, you can pass this with the parameter -u:

curl -u "apikey:<IBM Cloud API key value>"

import com.ibm.cloud.sdk.core.security.BasicAuthenticator;
import <sdk_base_package>.ExampleService.v1.ExampleService;
...
// Create the authenticator.
BasicAuthenticator authenticator = new BasicAuthenticator.Builder()
    .username("myuser")
    .password("mypassword")
    .build();

// Create the service instance.
ExampleService service = new ExampleService(authenticator);

// 'service' can now be used to invoke operations.

from ibm_cloud_sdk_core.authenticators import BasicAuthenticator

authenticator = BasicAuthenticator(<your_username>, <your_password>)
service = ExampleService(authenticator=authenticator)

import {
    "github.com/IBM/go-sdk-core/v5/core"
    "<appropriate-git-repo-url>/exampleservicev1"
}
...
// Create the authenticator.
authenticator := &core.BasicAuthenticator{
    Username: "myuser",
    Password: "mypassword",
}

// Create the service options struct.
options := &exampleservicev1.ExampleServiceV1Options{
    Authenticator: authenticator,
}

// Construct the service instance.
service := exampleservicev1.NewExampleServiceV1(options)

// 'service' can now be used to invoke operations.

The username is apikey and the password is the api key itself.