Getting started with RHSM APIs in tech preview

Updated -

Using RHSM APIs in the tech preview

We are currently looking for feedback on the implementation of our new API offerings. At the end of this document, there are links for support and feedback. Please let us know if you need anything or have any requests!

Using APIs in RHSM can help you more effectively keep track of and automate how you manage your Red Hat subscriptions and entitlement usage. By using APIs in RHSM, you can:

  • Control which tooling you use for which products
  • Better manage your system inventory
  • Update and secure your systems more efficiently
  • Continue receiving official support for your Red Hat products

In order to transition to using APIs for Red Hat Subscription Management, Red Hat has created a tech preview program for early access and feedback. Red Hat is in the process of decommissioning Red Hat Network (RHN), including access to its APIs. As a part of this effort, Red Hat has been developing and documenting support for RHSM.

Prerequisites

Red Hat Subscription Management APIs use OAuth 2.0 for authorization. To obtain a token and access the APIs, you will need the following pieces of information:

  • Client ID and Secret provided by Red Hat
  • Your Customer Portal credentials

Obtaining your Client ID and secret

To create new Client ID and secret, called an application, or view your existing RHSM API applications for your organization, visit the RHSM API keys page, linked at the bottom of this article.

Only one RHSM API application is necessary for each organization, although some customers may choose to create multiple keys to hand out to application developers so that an individual key can be suspended without interrupting other developers.

Installing the took Manager application

Red Hat recommends the official took Manager application. The download link is available at the bottom of this article. It can be used to obtain and manage API access tokens. Currently, Red Hat supports Red Hat Enterprise Linux, Fedora, Ubuntu, and Mac OS. The installation process depends on the operating system you are using.

Operating System Installation Instructions
Red Hat Enterprise Linux Download the installer found at the bottom of this article using Terminal. For example: sudo rpm -i took-installer-1.8.4-1.x86_64.rpm
Ubuntu Download the installer found at the bottom of this article using Terminal. For example: sudo apt install -y took-installer_1.8.4-1_amd64.deb
Mac OS Download the installer found at the bottom of this article, and decompress the file in Terminal, and then run the install script. For example: tar -zxvf took-installer-1.8.4-1.darwin.x86_64.tar.gz ./install.sh

Important: The examples in the script may not reflect the actual file names in the download file found below. Please make adjustments to the script using the actual file names if necessary.

Setting up a new authorization configuration

With took installed, set up a new authorization configuration:

  1. Run took setup.
  2. Choose whether or not to keep the configuration file encrypted. It is recommended that you choose encryption.
  3. Enter an encryption password.

Warning: took does not store your password. If you forget it, there is no way to recover it. If this happens, you will need to reinstall took.

  1. Follow the prompts for environment configuration.
    a. Server Profile: rh
    b. Name: anything you want
    c. Client ID: Client ID listed on the RHSM API Keys page
    d. Client Secret: Client Secret listed on the RHSM API Keys page
    e. Callback URL: leave blank
    f. OIDC flow (auth - authorization code flow, pwd - password grant flow, leave empty to use server profile default): leave blank

Note: Additional took help can be found by running ‘took help’ from the command line.

Assuming you configured took to use an authentication configuration named “rhsm”, a typical command line workflow looks like this:

  • Run: took token rhsm
    If running secure took, you will need to run ‘decrypt took’ first or enter your decryption password when prompted.

    • If necessary this will take you through authentication and print out an access token
  • You can use the token to make API calls until the token expires
  • Once the token expires, run: took token rhsm
  • This will refresh the token, and ask for authentication information if necessary.
  • A full example of a curl using took:
# curl -H "`took token -e rhsm <userName>`" https://api.access.redhat.com/management/v1/systems

took can be used from scripts as well.

  • Run: took token rhsm to authenticate.
    • If running secure took, you will need to run ‘decrypt took’ first or enter your decryption password when prompted.
  • Once authenticated, you can use token=took token rhsm from the scripts to obtain the latest token. This will also renew access tokens if necessary.
  • This can also be used from unsupervised scripts such as cronjobs. You must enter user credentials once to get the first access/refresh token, and took will refresh tokens as necessary without any user interaction (the refresh tokens do not expire).

Optional CLI tooling support

Install a JSON formatting tool, such as jq or json_reformat to receive more structured returns of your API calls.

  • jq is a command-line JSON processor which can be installed using the yum command: sudo yum install jq
  • json_reformat is a command-line JSON formatter that comes standard on Red Hat Enterprise Linux.

Developers familiar with standard OIDC libraries that supports OAuth 2.0 can use those libraries to build authorization to the Red Hat Subscription Management APIs into scripts and applications.

An option for testing APIs, or for users who access APIs less frequently, is to use a REST client. As long as your REST client supports OAuth 2.0 or custom form submission, you can use that client to access the Red Hat Subscription Management APIs. Some examples of popular REST clients include Postman, Advanced REST Client, and Restlet. In addition to the RHSM API Client ID & Secret for your account and your Customer Portal credentials, you will need:

  • Grant Type = Password
  • Token URL = https://sso.redhat.com/auth/realms/3scale/protocol/openid-connect/token

Accessing available Red Hat Subscription Management APIs

Red Hat provides a Swagger file to describe the specifications of the Red Hat Subscription Management APIs. The Swagger specification includes information about the API endpoints available, input parameters, expected output, and possible error responses. The swagger file can be imported into REST clients like Postman or RESTlet to automatically build a library of API calls. The RHSM API Swagger documentation can be found on the RHSM API Swagger page linked at the bottom of this article.

Contact Red Hat

If you run into problems and require support, please open a support case.

We would love feedback on the API implementation we have so far. If you have any suggestions, please feel free to let us know in our survey.

Resources for downloads and Swagger documentation

Close

Welcome! Check out the Getting Started with Red Hat page for quick tours and guides for common tasks.