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 - Required scopes depend on the endpoint type:
  • Standard endpoints: hxp iam.jti-capture
  • Integration endpoints (/integrations): hxp.integrations iam.jti-capture

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	hxai-discovery
User-Agent	Identifies your client application	MyApp/1.0

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.