Skip to main content

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: hxp hxp.integrations hxai-insight-discovery 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
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}}

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.