Skip to main content
Version: 2.20.0

Overview

API authentication overview​

Glasswall Halo supports two authentication methods: Basic and Bearer. Before making any API requests, authenticate using the method configured for your deployment.

Basic authentication​

If your system uses Basic authentication, obtain the organisation ID and token from your system administrator. Combine these values in the format organisation_id:token, then base64 encode the result.

Include the encoded value in the request header as shown below.

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Bearer authentication​

For Bearer authentication, obtain a bearer token from your identity provider. Once you have the token, include it in the request header as shown below.

Authorization: Bearer ZGVtbzpwQDU1dzByZA==

Note: please ensure that you use the appropriate authentication method as per your system's configuration. Using the correct authentication ensures successful access to the Glasswall Halo API and prevents any authorization issues.

API authentication on an SSO-enabled deployment​

Single Sign-On (SSO) and the API authentication described above are independent. SSO (OpenID Connect) controls how users sign in to the Halo portal; it does not change how the REST API is authenticated.

This means that on a deployment where the portal uses SSO (Microsoft Entra ID, Keycloak, Okta and so on):

  • If API authentication is enabled, API clients must send Basic credentials (organization ID and token) or a Bearer token on every request, exactly as on a non-SSO deployment. API authentication is separate from SSO and can be turned off by deploying with configuration.AuthenticationScheme=None—it is disabled by default until you enable it—in which case the API accepts requests without credentials.
  • When API authentication is enabled, a 401 Unauthorized on /api/... requests on an SSO-enabled appliance almost always means the API credentials were never provisioned (or are incorrect), rather than an SSO/identity-provider issue.

Provisioning and rotating Basic-auth API credentials​

Basic-auth credentials consist of an organization ID and one or more tokens, supplied to the API at deployment time as secrets and enabled with configuration.AuthenticationScheme=Basic. Multiple tokens can be associated with an organization (comma-separated), which lets you rotate a token by adding a new one and later removing the old one.

For the platform-specific steps to create these secrets and enable Basic authentication, see:

If you do not know whether API credentials were provisioned for your appliance, or you need them reset, contact Glasswall Support.

Learn more​

Last updated on