Table of Contents
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.
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 a 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.|
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:
took setupon an API client.
# took setup A new took.yaml file is created to store your API credentials and tokens. You have the option to keep these credentials and tokens as plain text, however password encryption will prevent accidental disclosure. Do you want to encrypt the configuration? (Y/n) Y Configuration/Token encryption password: Confirm password:
Choose whether or not to keep the configuration file encrypted. It is recommended that you choose encryption.
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.
These are the known server profiles: rh (oidc-auth) Enter the server profile for which you want to add a new authentication configuration: rh Enter name of the new authentication configuration: Provide Name ( Eg: rhsm-auth ) Client ID: [Client ID listed on the RHSM API Keys page](https://access.redhat.com/management/api) Client secret: [Client Secret listed on the RHSM API Keys page](https://access.redhat.com/management/api) Callback URL: Leave blank 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-auth”, a typical command line workflow looks like this:
took token rhsm-auth <userName>, pass the customer portal username
If running secure
took, you will need to run
decrypt tookfirst 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-auth <userName>
- 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-auth <userName>`" https://api.access.redhat.com/management/v1/systems
took can be used from scripts as well.
- Run: took token rhsm
- 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 rhsmfrom 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.