Authentication

Every HIO API request must identify the calling integration. HIO supports API keys for application-to-application access and bearer tokens for requests made with a user context.

The security section on each API reference page shows the credential types accepted by that operation. HIO may still restrict the projects, events, and organizations available to a valid credential.

Before you begin

Ask HIO for the following values:

• the API base URL for your environment;
• either an API key or a bearer token; and
• the identifiers of the projects, events, or organizations assigned to the credential.

Store these values in your application’s secret manager. The environment variables below are placeholders for local testing:

HIO_API_URL="https://api.example.com"
HIO_API_KEY="your-issued-api-key"
HIO_PROJECT_ID="00000000-0000-0000-0000-000000000000"

API key

Use an API key when a server, scheduled job, or other application calls HIO without acting as a particular user. Send the key in the x-api-key header.

curl --request GET \
  --url "$HIO_API_URL/api/projects/$HIO_PROJECT_ID" \
  --header "Accept: application/json" \
  --header "x-api-key: $HIO_API_KEY"

API-key access is assigned

An API key can be valid but lack access to a particular project or event. HIO must assign the integration to the requested resource and allow API-key access.

Bearer token

Use a bearer token when the request acts with a HIO user context. Send the token using the standard Authorization header and Bearer scheme.

HIO_ACCESS_TOKEN="your-issued-access-token"

curl --request GET \
  --url "$HIO_API_URL/api/projects/$HIO_PROJECT_ID" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $HIO_ACCESS_TOKEN"

Bearer-token access can depend on the user’s membership, permissions, token scope, and token expiration.

Sending credentials from JavaScript

Keep this code on a trusted server. Do not put an API key or long-lived token in JavaScript delivered to a web browser.

const response = await fetch(
  `${process.env.HIO_API_URL}/api/projects/${projectId}`,
  {
    headers: {
      Accept: 'application/json',
      'x-api-key': process.env.HIO_API_KEY,
    },
  },
);

if (!response.ok) {
  throw new Error(`HIO request failed with status ${response.status}`);
}

const contentType = response.headers.get('content-type') ?? '';
if (!contentType.includes('application/json')) {
  const details = await response.text();
  throw new Error(`HIO returned an unexpected response: ${details}`);
}

const project = await response.json();

Troubleshooting

If a request is rejected:

1. Confirm that the request uses the correct API URL for the credential’s environment.
2. Check the header name and make sure the value does not contain quotation marks or extra whitespace.
3. Confirm that the API key is assigned to the requested project, organization, or event.
4. For bearer tokens, confirm that the token has not expired and that its user still has the required membership and permissions.
5. Record the request path, response status, and response body for HIO support, but never include the credential itself.

Protect credentials

• Store credentials in a secret manager or protected environment setting.
• Never embed credentials in browser-delivered JavaScript or a mobile application bundle.
• Never commit credentials, include them in screenshots, or paste them into public AI tools.
• Request separate credentials for separate environments and integrations.
• Rotate a credential immediately if it may have been exposed.

Next, use the querying events guide to make an authenticated request with filters and pagination.