API Keys

🔑 API keys

API keys allow external applications and services to securely authenticate HTTP requests to GermainUX without using a username and password.

API keys use the Bearer authentication scheme and can be assigned only the permissions required by the integration.

⚙️ Before You Begin

To create, enable, disable, or delete API keys, your account must have the Manage Users permission.

API-key authentication must also be enabled globally in the GermainUX configuration.

✨ Create an API Key

1. Go to Germain Workspace > Left Menu > System > Auth Settings > API Keys.

2. Click Create API Key.

3. Configure the API key using the fields below.

4. Click Finish.

5. Copy the generated API key and store it securely.

The API key’s name, expiration date, and permissions cannot be changed after creation.

📋 API Key Settings

Grant only the privileges required by the application or service using the key.

🔧 Use an API Key

Include the API key in the HTTP Authorization header using the Bearer authentication scheme:

Authorization: Bearer <api-key>

The following JavaScript example queries GermainUX data using an API key:

fetch("https://<germainux-host>/query/query", {
  method: "POST",
  headers: {
    "Accept": "*/*",
    "Content-Type": "application/json",
    "Authorization": "Bearer <api-key>"
  },
  body: JSON.stringify({
    factType: "InternalEvent",
    measures: [
      "time.day",
      "time.month",
      "time.year",
      "avg(value)",
      "count(id)"
    ],
    orders: [
      "time.day asc",
      "time.month asc",
      "time.year asc"
    ],
    pivots: [
      "time.day",
      "time.month",
      "time.year"
    ],
    timeRange: [
      "2026-01-01T00:00:00+01:00",
      "2026-01-02T00:00:00+01:00"
    ],
    timeMode: "INTERSECTS",
    timeOffset: "+01:00",
    filter: "type == 'GermainAPM:Service CPU Usage'",
    ignoreCache: false
  })
});

Replace <germainux-host> with the hostname of your GermainUX environment and <api-key> with the generated key.

Do not embed API keys in publicly accessible browser code. Store them in a secure secret-management system and use them only from trusted applications or services.

⚙️ Manage API Keys

Go to:

Germain Workspace > Left Menu > System > Auth Settings > API Keys

From this page, administrators with the Manage Users permission can:

API key settings cannot be edited after creation. To change a key’s name, expiration date, or privileges:

1. Create a replacement key with the required settings.

2. Update the application or service to use the new key.

3. Confirm that requests succeed.

4. Disable or delete the previous key.

Disabling or deleting a key takes effect immediately. Requests using that key will fail with an HTTP 401 Unauthorized response.

🌐 Enable or Disable API-Key Authentication Globally

API-key authentication can be enabled or disabled for the entire GermainUX environment.

1. Open the GermainUX Config Console.

2. Navigate to:

germain.apm.services.authentication

3. Enable or disable:

bearerAuthenticationEnabled

4. Restart all Tomcat instances to apply the change.

When API-key authentication is disabled:

🔁 Rotate an API Key

To rotate a key without interrupting the integration:

1. Create a new key with the required privileges and expiration date.

2. Store the new key securely.

3. Update the external application or service.

4. Test an authenticated request.

5. Disable the old key.

6. Confirm that the integration continues to operate.

7. Delete the old key when it is no longer required.

🐛 Troubleshooting

If an API request fails, verify that:

• API-key authentication is globally enabled.

• All Tomcat instances were restarted after changing the global setting.

• The Authorization header uses the Bearer scheme.

• The complete API key was copied without additional spaces or characters.

• The key is enabled and has not expired.

• The key has the privileges required by the requested operation.

• The request URL and HTTP method are correct.

• The key has not been disabled, deleted, or replaced.

An HTTP 401 Unauthorized response generally indicates that the key is missing, invalid, expired, disabled, or that API-key authentication is globally disabled.

An HTTP 403 Forbidden response generally indicates that the key is valid but does not have sufficient privileges for the requested operation.

🛡️ Security Recommendations