Red Hat Entitlement Gateway: Vendor API Developer Guide

Updated -

About this guide

This guide details how to integrate to Red Hat Entitlement Gateway Vendor APIs via service account and provides additional information how this workflow will be consumed by the end Customers placing orders via independent software vendor (ISV) channels.

You or someone from your organization should already be in contact with Red Hat's Partner Integration team to get access to these APIs.

Contact Red Hat Partner Integration Development Team

Please reach out to your organization in contact with Red Hat’s partner integration team to get the unique slack channel link.

In case of any issues during integration or after related to the Red Hat Entitlement Gateway Vendor API’s, please ping us in the slack channel, this is the fastest way to get attention from Partner Integration team.

Open API Specification for Vendor API’s

Red Hat Entitlement Gateway has many APIs, however not everything is relevant for Vendor Integration, hence please filter by the “Vendor” type on the API’s. Please invoke the right Entitlement Gateway instance for preprod or production to send order data.

Pre-Production: Stage Environment

https://entitlement-gateway.stage.api.redhat.com/swagger-ui/index.html?urls.primaryName=Vendor

Production Environment

https://entitlement-gateway.api.redhat.com/swagger-ui/index.html?urls.primaryName=Vendor

Pre-Requisities

Before starting on API integration, please make sure that:

  1. A Red Hat Organization Account ("Corporate") account exists, and can be used to request Red Hat IAM accounts.
  2. Two Red Hat SSO IAM Service Accounts are requested from the Red Hat Organization Account in the previous step: one for preproduction and one for production. These service accounts will be used by the API later for OAuth.
  3. Getting Access to Red Hat Vendor API is complete and verified access works.

Using the JWT token to access the Vendor API

Please note that <valid-access-token> in the Authorization header should be replaced by the bearer token from the attribute access_token from the previous request

Example showing the format for authorization header in https request

curl --location 'https://entitlement-gateway.api.redhat.com/v1/...' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <valid-access-token>'
  • The result token access_token is a JWT that expires in 15 mins (900 seconds)
  • This temporary token can be used in the request Authorization header when calling service for authentication/authorization purposes

Integrating with Vendor Orders API

Once the Authorization flow is validated, the next step is to integrate with the vendor orders API. Please refer to the OpenAPI specs

V1 API Specification (Deprecated)

Create Vendor Order API for an example request/response.

V2 API Specification (New!)

To test order creation, please use the Stage environment entitlement-gateway.stage.api.redhat.com

When the order is created successfully, the API returns a unique link for each order. Vendors should securely communicate this link to the end customer for order connection. Customers are required to click on this link to complete the order connection.

An example order connection link https://console.redhat.com/connect/vendor/vendor-name/5ce74cc0-a341-4538-b8e9-de83521fd706

The Red Hat Customer Guide has detailed information to be shared with customers detailing the steps to connect an order. Please share this article along with the order confirmation.

Appendix

Pre-Requisite: Request a new Red Hat Organization Account

Please follow the instructions in - Red Hat Account Management FAQ

Note:
While creating a new account please choose the account type as “Corporate”.

Existing Customers:
If there is an existing Partner Organization Account, then there is an option to reuse this account. However, many teams choose to go ahead and request new org admin accounts to restrict service account access to a specific team or business unit.

Pre-Requisite: Request Red Hat SSO IAM service accounts

The Red Hat Vendor API uses OAuth 2.0 specification and requires a service account to be created with sso.redhat.com.

To integrate with the Vendor API for production, it is recommended to opt for “Corporate” type while requesting new Red Hat Accounts where the Service accounts will be later requested. The “Corporate” accounts allow “organization administrators” to facilitate administration of Service Accounts and ownership of secure credentials.

Note: Requesting Organization accounts is a one-time set up process, same account can be reused for other integrations

Red Hat API integration best practices recommend separating the service account credentials between preprod environments and production.
Two service accounts should be provided to Red Hat to allow authorization for API access:

  • A Service Account to integrate with Staging environment
  • A Service Account to integrate with Production environment

References
https://docs.redhat.com/en/documentation/red_hat_customer_portal/1/html/creating_and_managing_service_accounts/ref-ciam-svc-acct-api-creating-service-acct

Red Hat Account Management FAQ

  1. Create new Organization Accounts: https://access.redhat.com/articles/customer-service-accounts#createlogin
  2. Check if account is personal or corporate account: https://access.redhat.com/articles/customer-service-accounts#Check
  3. General account management questions: https://access.redhat.com/articles/customer-service-accounts

Pre-requisite: Getting Access to Red Hat Vendor API

Please email the Red Hat Partner Integration team providing the details of the Red Hat SSO Service Account, including both staging and production service account name and client ID. Partner Integration team will onboard both permission requests for preproduction and production together to save both teams time and effort whenever integration is production ready.

Example Email Template

Subject:
Requesting access to Red Hat's vendor APIs

Body:
I am requesting access via service account to Red Hat's vendor APIs.

Stage service account information:
- service account name: <your service account name here>
- client ID: <your client ID here>

Prod service account information:
- service account name: <your service account name here>
- client ID: <your client ID here>

API Integration: Troubleshooting and FAQ

Issue #1: HTTP 403 status accessing APIs using an access token

If integrating with the Red Hat Vendor API for the first time, please send a request to authorize access for both preprod and production service accounts on the Red Hat vendor APIs before using your credentials. Please refer to the section Request Access to Red Hat Vendor API

Issue #2: Unable to Access console.stage.redhat.com

console.stage.redhat.com is accessible only from the Red Hat Internal Network. If accessed from outside the network, this would show “Preprod lockdown: Access denied”. If end to end validation is required in preprod, Red Hat Partner Integration Team can assist with the order activation.

Issue #3: Other issues

To report any other issues to the Red Hat Partner Integration Team, please reach out via the slack channel or general Red Hat Support.

Glossary

Vendor
Also "ISV" or "Independent software vendor". This refers to the external entity or Partner selling Red Hat software/products. From the context of this workflow, Vendor works with Red Hat to provision entitlements for the customers.

Customer
One or more user(s) of Red Hat Products in their organization.

Order
Represents purchase of a Red Hat Product from a vendor. This is composed of one or more Red Hat entitlements. Each entitlement can be composed of one or many products. An entire order is linked to a single Red Hat account

Entitlements
The list of products and/or features included in the purchase with SKU and Quantity. A Red Hat Subscription is created for each entitlement.

Product
A single line item or SKU + quantity within an entitlement. Each SKU must be unique within an entitlement

Comments