Where do I go for X?

Public APIs:

environment	url	required header
production	https://cloud.redhat.com/api/cloudigrade/v2/	Authorization: Basic AbCdXyZ
stage	https://cloud.stage.redhat.com/api/cloudigrade/v2/	Authorization: Basic AbCdXyZ
ephemeral/local	http://localhost:8000/api/cloudigrade/v2/	X-RH-IDENTITY: (base64-encoded JSON)

Internal APIs:

environment	cert	url	required args
production	✅	https://mtls.internal.cloud.redhat.com/api/cloudigrade/internal/	--cert, --cert-key
production	❌	https://internal.cloud.redhat.com/api/cloudigrade/internal/	Cookie header
stage	✅	https://mtls.internal.cloud.stage.redhat.com/api/cloudigrade/internal/	--proxy, --cert, --cert-key
stage	❌	https://internal.cloud.stage.redhat.com/api/cloudigrade/internal/	--proxy, Cookie header
ephemeral/local	❌	http://127.0.0.1:8000/internal/	(none required)

Public APIs

How do I authenticate?

For prod and stage, HTTP Basic access authentication is handled upstream by the Insights 3scale server and automatically generates the X-RH-IDENTITY header that will be sent to our service.

• In production, use real credentials for a real Red Hat customer account that has org admin set.
• In stage, create a user via Ethel, assign subscriptions via Ethel (try RH00003, RH00004, ES0113909, and SVC3124), and wait. Even though the user may appear to be ready in the Ethel UI, other backend systems may not have synchronized. I suggest waiting one full hour before expecting complete availability.

Since ephemeral and local environments do not sit behind 3scale, requests cannot use basic auth. Instead, you must simulate 3scale's custom X-RH-IDENTITY request header. See the examples below or REST API Examples for reference.

httpie examples

Important note: Stage sits behind a Squid proxy and requires VPN access. Only the prod environment is publicly accessible.

prod:

http --auth $REDHAT_USERNAME:$REDHAT_PASSWORD \
    https://cloud.redhat.com/api/cloudigrade/v2/sysconfig/

stage:

http --auth $REDHAT_USERNAME:$REDHAT_PASSWORD \
 --proxy="https:http://squid.corp.redhat.com:3128" \
 https://cloud.stage.redhat.com/api/cloudigrade/v2/sysconfig/

ephemeral or local:

# port-forward access to the pod if necessary
POD_NAME=$(oc get pods -o jsonpath='{.items[*].metadata.name}' -l pod=cloudigrade-api  | awk '{print $1}')
oc port-forward pods/"${POD_NAME}"  8000:8000 &

HTTP_X_RH_IDENTITY=$(echo '{"identity":{"account_number":"6089719","user":{"is_org_admin":true}}}' | base64)
http 127.0.0.1:8000/api/cloudigrade/v2/sysconfig/ \
    "X-RH-IDENTITY:${HTTP_X_RH_IDENTITY}"

Internal APIs

cloudigrade's internal APIs exist to perform internal, not-customer-facing queries and ad-hoc operations. The internal APIs are generally unsupported because they are expected only to be used by the dev team in a limited fashion. If you think you need to use an internal API, please contact the cloudigrade devs to explain your use case first.

All requests to internal prod and stage require a VPN connection, and most require the Squid proxy (--proxy "https:http://squid.corp.redhat.com:3128")

Authentication and authorization to these APIs uses Turnpike. Authorization is dependent on the user having the doppler-dev role. To add a user or change membership, use rover for the production environment, and rover in stage for the stage environment. Turnpike is configured to check for this role here.

All of the internal urls are mapped from /internal/ -> /api/cloudigrade/internal/, this means that our internal APIs live at /api/cloudigrade/internal/api/cloudigrade/v1/. While the root url at https://internal.cloud.redhat.com/api/cloudigrade/internal/api/cloudigrade/v1/ requires a valid identity header and user to access, the specific views (e.g. /api/cloudigrade/internal/api/cloudigrade/v1/users/, /api/cloudigrade/internal/api/cloudigrade/v1/accounts/, etc.) only requires the user have the required Rover role.

To access the mTLS hostnames, use the certs that were shared privately with dev team members in Google Drive. Currently, we have no way to access the non-mTLS hostnames strictly from command-line tools. The Turnpike team suggests you instead:

• access the API first in a web browser to get a valid SSO session,
• inspect the browser's data, and copy the session cookie from the browser, and
• include that cookie in subsequent command-line requests with the Cookie header.

httpie examples for internal APIs

prod with cert auth:

http \
    --cert=cloudigrade-turnpike-prod.crt --cert-key=cloudigrade-turnpike-prod.key \
    https://mtls.internal.cloud.redhat.com/api/cloudigrade/internal/api/cloudigrade/v1/users/

prod with cookie auth:

read -s PROD_SESSION # then paste your prod session cookie value
http \
    https://internal.cloud.redhat.com/api/cloudigrade/internal/api/cloudigrade/v1/users/ \
    "Cookie:session=${PROD_SESSION}"

stage with cert auth:

http \
    --proxy="https:http://squid.corp.redhat.com:3128" \
    --cert=cloudigrade-turnpike-stage.crt --cert-key=cloudigrade-turnpike-stage.key \
    https://mtls.internal.cloud.stage.redhat.com/api/cloudigrade/internal/api/cloudigrade/v1/users/

stage with cookie auth:

read -s STAGE_SESSION # then paste your stage session cookie value
http \
    --proxy="https:http://squid.corp.redhat.com:3128" \
    https://internal.cloud.stage.redhat.com/api/cloudigrade/internal/api/cloudigrade/v1/users/ \
    "Cookie:session=${STAGE_SESSION}"

ephemeral or local:

# port-forward access to the pod if necessary
POD_NAME=$(oc get pods -o jsonpath='{.items[*].metadata.name}' -l pod=cloudigrade-api  | awk '{print $1}')
oc port-forward pods/"${POD_NAME}"  8000:8000 &

http 127.0.0.1:8000/internal/api/cloudigrade/v1/users/