SupportConsoleDevelopersStart a trialContact

Chapter 3. API call authentication

You must authenticate API calls to Satellite Server by using SSL certificates and valid user credentials, with options for HTTP basic authentication, SSL client certificates, or personal access tokens.

3.1. SSL authentication overview
Copy link

Red Hat Satellite requires HTTPS for all API communications to provide encryption and identity verification. You can use either self-signed certificates or custom SSL certificates you configure.

Satellite 6.19 does not support non-SSL communications.

By default, Satellite Server uses a self-signed certificate. This certificate acts as both the server certificate to verify the encryption key and the certificate authority (CA) to trust the identity of Satellite Server.

Additional resources

3.2. Configuring SSL authentication
Copy link

Configure SSL authentication to enable secure API requests to Satellite by installing and trusting the CA certificate.

Procedure

  1. Obtain a certificate from your Satellite Server by using one of the following options:

    • If you plan to call the API from a remote server, download the CA certificate: 

      $ curl \
--output /etc/pki/ca-trust/source/anchors/satellite.example.com-katello-server-ca.crt \
http://satellite.example.com/pub/katello-server-ca.crt

    • If you plan to call the API directly on your Satellite Server, copy the certificate to the /etc/pki/ca-trust/source/anchors directory: 

      # cp /var/www/html/pub/katello-server-ca.crt /etc/pki/ca-trust/source/anchors/satellite.example.com-katello-server-ca.crt

  2. Add the certificate to the list of trusted CAs: 

    $ update-ca-trust extract

Verification

  • Verify that your client trusts the Satellite SSL certificate by entering the API request without the --cacert option: 

    $ curl \
--request GET \
--user My_User_Name:My_Password \
https://satellite.example.com/api/v2/hosts

3.3. HTTP authentication overview
Copy link

You must provide valid Satellite credentials to access the Satellite API.

The API uses HTTP Basic authentication to send encoded user credentials in the Authorization header. If a request does not include an appropriate Authorization header, the API returns a 401 Authorization Required error.

Important

Basic authentication involves potentially sensitive information, for example, it sends passwords as plain text. The REST API requires HTTPS for transport-level encryption of plain text requests.

Some base64 libraries break encoded credentials into multiple lines and terminate each line with a newline character. This invalidates the header and causes a faulty request. The Authorization header requires the encoded credentials to be on a single line within the header.

Additional resources

3.4. Token authentication overview
Copy link

You can use Personal Access Tokens to authenticate API requests instead of passwords. Additionally, you can manage your security by setting expiration dates or revoking tokens at any time.

3.4.1. Creating a Personal Access Token
Copy link

Create a Personal Access Token to authenticate API requests without sharing your password.

Prerequisites

  • Your user account has a role that grants the create_personal_access_tokens permission.

Procedure

  1. In the Satellite web UI, navigate to Administer > Users.
  2. Select a user for which you want to create a Personal Access Token.
  3. On the Personal Access Tokens tab, click Add Personal Access Token.
  4. Enter a Name for you Personal Access Token.
  5. Optional: Select the Expires date to set an expiration date. If you do not set an expiration date, your Personal Access Token will never expire unless revoked.

  6. Click Submit. You now have the Personal Access Token available to you on the Personal Access Tokens tab.

    Important

    Ensure to store your Personal Access Token as you will not be able to access it again after you leave the page or create a new Personal Access Token. You can click Copy to clipboard to copy your Personal Access Token.

Verification

  1. Make an API request to your Satellite Server and authenticate with your Personal Access Token: 

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://satellite.example.com/api/status

  2. You should receive a response with status 200, for example: 

    {"satellite_version":"6.19.0","result":"ok","status":200,"version":"3.5.1.10","api_version":2}

    If you go back to Personal Access Tokens tab, you can see the updated Last Used time next to your Personal Access Token.

3.4.2. Revoking a Personal Access Token
Copy link

Revoke a Personal Access Token before its expiration date when a token is compromised or no longer needed for API access.

Procedure

  1. In the Satellite web UI, navigate to Administer > Users.
  2. Select a user for which you want to revoke the Personal Access Token.
  3. On the Personal Access Tokens tab, locate the Personal Access Token you want to revoke.
  4. Click Revoke in the Actions column next to the Personal Access Token you want to revoke.

Verification

  1. Make an API request to your Satellite Server and try to authenticate with the revoked Personal Access Token: 

    $ curl \
--user My_Username:My_Personal_Access_Token \
https://satellite.example.com/api/status

  2. You receive the following error message: 

    {
  "error": {"message":"Unable to authenticate user My_Username"}
}
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top