Authentication and API access

Cogsol supports different authentication patterns depending on where the integration runs and whether it needs to identify an individual user. Access is provisioned per tenant.

What every protected API request needs

Protected Cogsol endpoints require both of these headers:

Authorization: Bearer <access-token>
X-API-Key: <api-key>

The two values have different purposes:

• The bearer token identifies the calling application or user.
• The API key associates the request with an authorized Cogsol tenant.

An API key is not a replacement for an access token.

info

Credentials and permissions are environment-specific. Development credentials should not be reused in production.

Choose an authentication pattern

Pattern	How it works	Best for
1. Server-to-server credentials	Your backend obtains tokens using credentials securely stored on the server.	Backends, backend-for-frontend (BFF) services, jobs, and automations.
2. Cogsol-managed browser access	Cogsol issues the browser a short-lived token, so the frontend never stores a client secret.	SPAs that use low-risk agents and do not require end-user authentication with Cogsol.
3. Customer identity-provider integration	In a dedicated or on-premises deployment, Cogsol integrates with the customer's identity provider, identifying client users and groups.	Customer applications that need Cogsol to recognize and authorize each end user.

1. Server-to-server credentials

Use this pattern when the caller runs in a trusted backend, server, job, or automation. Cogsol provisions a technical client for the tenant and grants it only the required API operations.

Keep the client secret in a secret manager or server-side environment. Never include it in browser JavaScript, a mobile application, or a distributed desktop application.

What you provide to Cogsol: the target tenant, required APIs and operations, and a technical contact for secure credential delivery.

What Cogsol provides: the API and token URLs, client ID, client secret, OAuth scope, and API key.

What you implement: server-side token acquisition and renewal, secure secret storage, and the calls to the Cogsol APIs.

1. Request an access token

curl --request POST "$COGSOL_TOKEN_URL" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$COGSOL_CLIENT_ID" \
  --data-urlencode "client_secret=$COGSOL_CLIENT_SECRET" \
  --data-urlencode "scope=$COGSOL_SCOPE"

The response includes an access token and its lifetime:

{
  "access_token": "<token>",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Cache the token server-side and renew it shortly before it expires. Do not request a new token for every API call.

2. Call a Cogsol API

In this example, COGSOL_API_BASE_URL includes the service path supplied by Cogsol, such as the Cognitive service path.

curl --request GET "$COGSOL_API_BASE_URL/assistants/" \
  --header "Authorization: Bearer $COGSOL_ACCESS_TOKEN" \
  --header "X-API-Key: $COGSOL_API_KEY"

See the Cognitive API and Content API references for available operations.

2. Cogsol-managed browser access

Use this pattern for SPAs that use low-risk agents, do not need Cogsol to identify the end user, and only require approved runtime operations. It must not be used to configure agents, content, tools, secrets, or other tenant resources.

Any value shipped with the frontend can be inspected and copied from the browser. This method is provided so you don't have to save a client secret.

What you provide to Cogsol: the exact frontend origins, target tenant, and runtime operations required.

What Cogsol provides: the authentication and API URLs, and API key. The technical client and its secret remain inside Cogsol.

What you implement: requesting and renewing the short-lived browser token and including it with the API key in Cogsol API calls.

The frontend requests a token from a Cogsol endpoint such as:

POST <cogsol-auth-base-url>/public/client-token
Origin: https://your-approved-frontend.example

Then you include the returned token in subsequent API calls:

Authorization: Bearer <access-token>
X-API-Key: <api-key>

warning

An origin allow-list and CORS are not proof of client identity: non-browser software can imitate an Origin header. Use the managed browser flow only for low-risk, restricted access. If stronger protection is required, use pattern 1 with a BFF.

3. Customer identity-provider integration

This pattern may be suitable when Cogsol runs in a dedicated or on-premises deployment integrated with the customer's identity provider. Its availability and design must be validated with our support or engineering teams.

Use this deployment-specific pattern when Cogsol must recognize and authorize each customer user. The customer identity provider is responsible for authenticating users and providing Cogsol with a token that identifies the user and their groups.

Alternative: use agents without a direct API integration

Cogsol can provide a hosted frontend that the customer embeds in an existing site, for example through an iframe.

Roles and endpoint permissions

Authentication does not grant access to every API.

For customer integrations, Cogsol commonly assigns one of the following roles:

Role	Typical intent
user	Use agents through chat, and async executions
reporter	Use and test agents, creating reports and evaluation datasets
contentcontributor	Read and contribute documents, ingestion, metadata, and related content configuration
reader	Broad read access across tenant resources
implementer	Configure and implement agents, content, tools, secrets, evaluation, and analysis resources
admin	Broad tenant configuration and administration, including pricing, promotion, and cost-related access

Credential handling

• Never store or expose a client secret in a SPA, static frontend, browser bundle, frontend build variable, mobile application, or distributed desktop application.
• Do not log access tokens, client secrets, or complete API keys.
• Use different credentials for development and production.
• Rotate credentials periodically and immediately after suspected exposure.
• Revoke credentials that are no longer in use.