Obtaining and updating an API token

Obtain the License Service API token to authenticate and retrieve license usage data. Learn how to update the token to comply with your security policies if needed.

License Service API token is a basic authentication method for connecting with License Service APIs. If you require to configure advanced API authentication, see Service account token.

Using the License Service API token

To connect to the API endpoint, you need to provide a secure authentication token as the URL parameter in the API URL.

The following examples show how to use a License Service token in your API URL:

API API URL format
Retrieving an audit snapshot <License Service URL>/snapshot?token=<token>
Retrieving license usage of products <License Service URL>/products?token=<token>
Retrieving license usage of bundled products <License Service URL>/bundled_products?token=<token>
Retrieving contribution of services <License Service URL>/services?token=<token>
Retrieving information about License Service health <License Service URL>/health?token=<token>
Obtaining the status page <License Service URL>/status?token=<token>

Note: You do not need to use an API to retrieve information about the version of License Service that is deployed on a cluster.

Obtaining an API token

Obtaining an API token by using the CLI

Note: The commands assume that the IBM Cloud Pak foundational services are installed in ibm-common-services namespace. If IBM Cloud Pak for Integration installs foundational services in a different namespace, adjust the commands.

  • For Linux and OSX run the following commands.

    • Linux:

      kubectl get secret ibm-licensing-token -o jsonpath={.data.token} -n ibm-common-services | base64 -d
      
    • OSX:

      kubectl get secret ibm-licensing-token -o jsonpath={.data.token} -n ibm-common-services | base64 -D
      

      The value that you get in the response is your API token.

  • For Windows run the following command.

    • Windows:

      kubectl get secret ibm-licensing-token -o jsonpath={.data.token} -n ibm-common-services`
      

      The token that you retrieve is encoded. To decode the token, you can use the Certificate Services, if available. Run the following commands to retrieve and encode the token with Certificate Services:

      kubectl get secret ibm-licensing-token -o jsonpath={.data.token} -n ibm-common-services > token_encoded
      
      certutil -decode token_encoded token_decoded
      
      type token_decoded
      

      Otherwise, obtain the token by using the OpenShift console. Complete the steps in the following procedure.

Obtaining an API token by using the OpenShift console

  1. Log in to the OpenShift console of the cluster where you deployed License Service.
  2. Go to Workloads > Secrets.
  3. Set the project to All Projects.
  4. Find the ibm-licensing-token and select it.
  5. Scroll to the Data section and copy the token by using the Copy to Clipboard option.

Updating an API token

Important: The API token cannot contain spaces or the following characters ?,%, and &.

Updating an API token by using the CLI

Note: The commands assume that the IBM Cloud Pak foundational services are installed in ibm-common-services namespace. If IBM Cloud Pak for Integration installs foundational services in a different namespace, adjust the commands.

  1. Create a token.yml file with the following contents. Provide your new token as <TOKEN>.

     apiVersion: v1
     kind: Secret
     metadata:
       labels:
         app.kubernetes.io/component: ibm-licensing-service-svc
         app.kubernetes.io/instance: ibm-licensing-service
         app.kubernetes.io/managed-by: operator
         app.kubernetes.io/name: ibm-licensing-service-instance
         release: ibm-licensing-service
       name: ibm-licensing-token
       namespace: ibm-common-services
     type: Opaque
     stringData:
       token: <TOKEN>
    
  2. To apply the new token, run the following command.

    kubectl apply -f token.yml
    
  3. To refresh the application by deleting the pod, run the following command.

    kubectl delete pods -l app=ibm-licensing-service-instance -n ibm-common-services
    

Updating an API token by using the OpenShift console

  1. Open the OpenShift console of the cluster where you deployed License Service.
  2. Go to Workloads > Secrets.
  3. Set the project to All Projects.
  4. Find the ibm-licensing-token and select it.
  5. From the Actions list, select Edit Secret.
  6. Edit the secret value and click Save.

Disabling the API token as URL parameter

If your security policy does not allow you to provide a token as a URL parameter, you can disable this option. Then, you must use a service account token as an authentication method. Before you change the authentication method, see Service account token.

  1. Edit the IBMLicensing custom resource.

  2. Add the following lines to the IBMLicensing section, under spec:

    features:
      auth:
        urlBasedEnabled: false
    

    Note: To turn the License Service token authentication back on, remove these lines from the custom resource.