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 application's client identifier
  • Client Secret - Your application's client secret
  • Username/Password - For standard user authentication (password grant)
  • Scope - Required scopes: openid profile hxp iam.permissions.bulk hxai-insight-discovery

See Getting Started for detailed setup instructions.

IAM Configuration​

Base IAM URL: https://auth.iam.dev.experience.hyland.com/

Use this URL as the base for all authentication requests:

POST {IAM_BASE_URL}/idp/connect/token

Authentication Methods​

Method 1: Standard User Authentication (Password Grant)​

For standard users authenticating with username and password credentials.

Use Cases:

  • Web applications with user login
  • Development and testing
  • Interactive applications
### Get Access Token (Standard User)
POST {{iam_base_url}}/idp/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=password&username={{username}}&password={{password}}&scope={{scope}}&client_id={{client_id}}&client_secret={{client_secret}}

Method 2: Service User Authentication (Client Credentials)​

For service accounts and server-to-server authentication.

Use Cases:

  • Backend services
  • Batch processing jobs
  • System integrations
  • Scheduled tasks
### Get Access Token (Service User)
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:

  • Invalid username or password
  • 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.