Skip to main content

Authentication

The Knowledge Enrichment APIs use bearer token authentication with JSON Web Tokens (JWTs). Every request to a protected resource must include a valid JWT in the Authorization header. This topic covers the setup from a new account through to a working token.

Token endpoint: POST /connect/token

The following diagram shows the sequence of the authentication process. An administrator registers an external client and provides its credentials to the developer. The developer exchanges those credentials for an access token at the token endpoint and then includes the token in each call to the Knowledge Enrichment API.

Step 1 — Account Setup​

Before you can request a token, you need a registered external client in your Content Innovation Cloud environment.

Getting a Subscription​

Your environment must have a subscription to the API you intend to call, either the Context API or the Data Curation API. You can view the subscriptions for an environment in the Content Innovation Cloud Administration Portal. For more information, see Subscriptions.

Creating a Service Account​

Because Hyland hosts the APIs, Hyland provides the endpoints used to access them. To call those endpoints, you need a service account registered in the environment you intend to use. Hyland provides the initial administration account for Content Innovation Cloud. You can then configure additional accounts. For more information, see Metadata for SAML Identity Providers.

Creating a User Group​

Create a user group with either the Data Curation User or the Context API User role assigned to it. To check for existing user groups, log on to the Content Innovation Cloud Administration Portal. For more information on the roles available and how to assign them, see Assigning User Groups to Roles

If no user group is configured, create one. For more information, see Creating a User Group.

Registering an External Client​

External applications can call the Knowledge Enrichment APIs for custom integrations. Before an external application can request an access token, an administrator must register it as a client. For more information, see Registering an External Application for more information.

caution

The Client Secret is displayed only once. Save it immediately. If you lose the client secret, you must reset it. For more information see, Resetting the Secret for an External Application.

Scopes for External Applications​

External applications require the following scope:

ScopePurpose
environment_authorizationRequired for all Knowledge Enrichment API calls, including the Context API and the Data Curation API

For more information, see Scopes for External Applications.

Step 2 — Obtaining an Access Token​

Send a POST request to the token endpoint for your environment:

EnvironmentToken endpoint
Production (US)https://auth.app.hyland.com/idp/connect/token
Production (EU)https://auth.app.hyland.eu/idp/connect/token
curl -X POST https://auth.app.hyland.com/idp/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=environment_authorization"

A response similar to the following is displayed:

{
  "access_token": "jwt.access.token",
  "expires_in": 900,
  "token_type": "Bearer",
  "scope": "environment_authorization"
}

Save the access_token.

FieldTypeDescription
access_tokenstringThe JWT bearer token to include in API requests.
expires_inintegerThe token lifetime in seconds. In the preceding response, 900 seconds is 15 minutes.
token_typestringThe token type, Bearer.
scopestringThe granted scopes.

Step 3 — Use the Token in API Requests​

Include the token in the Authorization header of each request to a protected endpoint:

Authorization: Bearer <access_token>

For Example:

curl -X POST \
  "https://knowledge-enrichment.ai.app.hyland.com/latest/api/data-curation/presign" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"chunking": true}'

Authentication Errors​

401 Unauthorized​

This response is returned when the token is missing or invalid:

{
  "message": "Unauthorized"
}

Causes:

  • No Authorization header provided
  • Token is malformed or has an invalid signature
  • Token issuer does not match expected authority
  • Token cannot be verified with the public key
  • Token does not contain the hxp_authorization claim

If the token is expired, the response body is different. Tokens are valid for 15 minutes.

{
  "Message": "Token has expired."
}

Resolution:

  • Verify that you are sending a valid Bearer token in the Authorization header
  • If the token was recently obtained, ensure your client credentials and token endpoint are correct
  • For expired tokens, request a new token using the same token endpoint

403 Forbidden — Insufficient Permissions​

Returned when the token is valid but the service account lacks the required permission:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have the required permission to access this resource."
  }
}

Required permissions:

  • Data Curation API: cin-data-curation.api.submit
  • Context API: Requires the Context API User role assigned to the user group

Resolution: Verify that the service account's user group has the correct role assigned. See Step 1 for role assignment details.

Required Permissions​

Both APIs use the same token endpoint and the environment_authorization scope. The user group assigned to your service account determines which APIs are accessible:

RoleAPI access
Data Curation UserData Curation API
Context API UserContext API

If a request returns a 403 Forbidden response and the token is valid, verify that the user group of the service account has the correct role assigned.

Next Steps​