Authentication

Knowledge Discovery uses OAuth 2.0 for authentication. This guide covers the two authentication methods and common errors.

Prerequisites

Before authenticating, ensure you have:

• IAM Base URL - Example: https://auth.iam.experience.hyland.com/

• Client ID - Your client identifier

• Client Secret - Your client secret

• Scope and application key - Required values depend on the API flow:

  Knowledge Discovery implementation and API flow	Hxp-App	Required token scope
  ECE-powered Agent management, Agent discovery, and Conversation endpoints	cin-ece-kd	hxp
  Legacy Agent management, Agent discovery, and single-shot question endpoints	hxai-discovery	hxp iam.jti-capture
  Legacy integration endpoints (/integrations)	hxai-discovery	hxp.integrations iam.jti-capture

  ECE-powered Knowledge Discovery requires the cin-ece-kd application key. The iam.jti-capture scope is not required when using this key.

See Getting Started for detailed setup instructions.

IAM Configuration

Use this URL as the base for all authentication requests:

POST {IAM_BASE_URL}/idp/connect/token

Authentication Method

Service User Authentication

Use Cases:

• Backend services
• Batch processing jobs
• System integrations
• Scheduled tasks

HTTP

POST {{iam_base_url}}/idp/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope={{scope}}&client_id={{client_id}}&client_secret={{client_secret}}

curl

curl -X POST "${IAM_BASE_URL}/idp/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=${SCOPE}" \
  -d "client_id=${CLIENT_ID}" \
  -d "client_secret=${CLIENT_SECRET}"

Required Request Headers

Every API request must include the following headers:

Header	Description	Example
Authorization	Bearer token obtained from the IAM token endpoint	Bearer eyJhbGci...
Hxp-Environment	Your unique environment key identifier	my-environment-key
Hxp-App	The application key for your Knowledge Discovery implementation and API flow	cin-ece-kd or hxai-discovery
User-Agent	Identifies your client application	MyApp/1.0

Application key

The Agent management and Agent discovery paths are shared by the legacy and ECE-powered implementations. Use cin-ece-kd when Knowledge Discovery is powered by ECE, and use hxai-discovery for legacy Knowledge Discovery. Do not determine the application key from the /agent path alone.

Conversation endpoints require ECE-powered Knowledge Discovery and cin-ece-kd. Legacy single-shot question and /integrations endpoints use hxai-discovery.

warning

If your HTTP client doesn't add the User-Agent header by default, make sure to include it in all requests below (e.g., User-Agent: PostmanRuntime/7.28.4) to avoid receiving a 403 Forbidden response.

Common Authentication Errors

401 Unauthorized

Causes:

• Expired access token
• Invalid access token
• Missing Authorization header

Solution:

{
  "type": "https://tools.ietf.org/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The access token is invalid or expired"
}

Obtain a new access token using one of the authentication methods above.

403 Forbidden

Causes:

• Insufficient permissions
• User not authorized for the resource
• Missing required scope

Solution:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "User does not have permission to access this resource"
}

Verify your user has the appropriate Discovery Manager role and required scopes.

400 Bad Request (Invalid Grant)

Causes:

• Expired or invalid client credentials
• Incorrect scope

Solution:

{
  "error": "invalid_grant",
  "error_description": "The specified grant is invalid"
}

Verify your credentials are correct and that the scope matches your environment configuration.

Token Management

Store access tokens securely and never commit them to version control. Use environment variables or secure vault services for credential storage.