Skip to main content

Authorization

Overview​

Agent Builder Platform supports three methods of authentication using NCP IAM:

  • Login Authorization: for interactive users via the Agent Builder Studio

  • Client Credentials - External Application: for external customers only - service-to-service or automated integrations interacting directly with Agent Builder Platform APIs using a mapped Service User

  • Client Credentials - Restricted Scope: for internal Hyland consumers only - service-to-service or automated integrations interacting directly with Agent Builder Platform APIs with no user context

One of the following IAM roles is required:

  • Consumer: Only invoke agents

  • Solution Builder: Create, invoke, and update agents

  • Administrator: Create, invoke, update, and delete agents

    • Note: Administrator role is automatically used with restricted scope auth

Login Authorization​

This method is intended for users accessing the APIs through Agent Builder Studio.

How It Works​

  • Users are redirected to our login page, where they enter IAM credentials
  • After successful authentication, a session is established and users are logged into the Agent Builder Studio
  • This token is automatically used by the Agent Builder Studio to make authenticated API calls

Guide​

  1. Reach out to your point of contact to add your user profile to the desired environment's IAM (sandbox, dev, staging, prod)
    • Specify what role you will require (see above)
    • You will get an email to set your password
  2. Navigate to Agent Builder Studio, where you will be redirected to the login screen and provide the credentials you just setup
  3. You will now have access to use Agent Builder Studio with the role provided to your user

Client Credentials Authorization - External Customers​

This method is intended for users accessing the APIs directly from an external service.

How It Works​

  • External Applications are created in IAM Admin Portal and linked to a Service User with the necessary role
  • Each service manages the client ID / secret for their External Application
  • A POST request to the IAM /connect endpoint with the client credentials for the External Application returns a JWT bearer token
  • The token is then used authenticate API calls

Guide​

  1. Reach out to your point of contact to gain access to the desired environment's IAM Admin Portal (sandbox, dev, staging, prod)

    • You will get an email to set your password

  2. Log into the IAM Admin Portal at https://admin.ENV.experience.hyland.com/, where ENV is the environment you are working in.

  3. Under Identity -> Users, choose Create Service User

    • Enter a username related to your service's function (ex. product-name-service-user)
    • Select the least privileged user group for your service.
      • e.g. if your service will only be invoking agents but not creating, select Agent Studio Solution Consumers
    • Enter a name for the client the service user will be connected to (ex. product-name-service-client)
    • Create and make sure you copy the Client ID and Client Secret that are generated
      • Note that you are responsible for managing the client secret for your service

  4. Your client will now be displayed under External Systems -> External Applications

    • Add the environment_authorization scope
    • Select Content Intelligence Agent Builder Testing as Environment
    • Select cin-agent-builder as Application
    • Save the client

  5. Send a POST request to generate a token:

curl -X POST  https://auth.iam.<ENV>.experience.hyland.com/idp/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "scope=hxp environment_authorization" \
  -d "grant_type=client_credentials"
  1. Use the access_token from the response body for requests to the Agent Orchestration API in the Authorization header

Client Credentials Authorization - Internal Hyland Consumers Only​

This method is intended for users accessing the APIs directly from an internal Hyland service.

How It Works​

  • Client Credentials clients are provisioned via Terraform Provider
  • The client ID is mapped to the restricted Agent Builder scope
  • A POST request to the IAM /connect endpoint with the client credentials returns a JWT bearer token
  • The token is then used authenticate API calls, passing environment information via headers

Guide​

  1. Provision a new Client Credentials client in the Terraform Infrastructure repository

  2. Submit an HXIAM ticket to map the new client ID to the restricted Agent Builder Scope

  3. Send a POST request to generate a token:

curl -X POST  https://auth.iam.<ENV>.experience.hyland.com/idp/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>" \
  -d "scope=hxp <restricted scope>" \
  -d "grant_type=client_credentials"

  1. Use the access_token from the response body for requests to the Agent Orchestration API in the Authorization header

  2. Add X-AccountID, X-EnvironmentID, and X-User-Context headers to the request to pass the NCP environment and user context.