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 Service User

IAM permissions are defined to read, create, edit, invoke, and delete agents.

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 permissions 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 permissions provided to your user

Client Credentials Authorization - External Application​

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 permissions
  • 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 to 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 and hxp scopes
    • Select your 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 to 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-Account-ID, X-Environment-ID, and X-User-Context headers to the request to pass the NCP environment and user context.