Red Hat SummitEste contenido no está disponible en el idioma seleccionado.
Chapter 2. Interacting with the API
Secure your interaction with the OpenShift Lightspeed API by obtaining authentication tokens, configuring request headers for Model Context Protocol (MCP) servers, and troubleshooting common authentication errors.
2.1. Authenticate API requests
Authenticate every request to a protected OpenShift Lightspeed endpoint by including a bearer token in the Authorization header to ensure secure access to the API.
Procedure
Set the
Authorizationheader using the following format:Authorization: Bearer <token>Submit the request. The following example demonstrates a query sent through
curl:curl -H "Authorization: Bearer ${TOKEN}" \ -H "Content-Type: application/json" \ https://<ols_host>/v1/query \ -d '{"query": "How do I create a deployment?"}'
2.2. Provide authentication for MCP servers
Authenticate proxy calls to Model Context Protocol (MCP) servers by identifying required headers and including credentials in your API request body.
Procedure
Identify required headers by calling the following endpoint:
GET /v1/mcp/client-auth-headersInclude the required credentials in the
mcp_headersfield of your JSON request body:{ "query": "Show GitHub issues", "mcp_headers": { "github-mcp": {"Authorization": "Bearer <github_token>"} } }
2.3. OpenShift Lightspeed API authentication requirements
The following table lists the OpenShift Lightspeed endpoints and their authentication requirements.
| Endpoint | Method | Authentication Required | Virtual Path |
|---|---|---|---|
|
| POST | Yes |
|
|
| POST | Yes |
|
|
| GET, PUT, DELETE | Yes |
|
|
| POST | Yes |
|
|
| POST | Yes |
|
|
| POST | Yes |
|
|
| POST | Yes |
|
|
| GET | No | — |
|
| GET | No | — |
|
| GET | No | — |
2.4. Access the OpenShift Lightspeed REST API directly
You can integrate Red Hat OpenShift Lightspeed with external tools and scripts by using the OpenShift Lightspeed REST API. Use the versioned endpoints to programmatically interact with the service and extend its capabilities into your existing workflows.
All versioned API endpoints use the /v1 path, such as, https://<route-host>/v1/<endpoint>.
Direct API access supports up to 100 concurrent connections. Behavior beyond this limit is currently unsupported.
Prerequisites
- OpenShift Lightspeed is installed and running thorugh the OpenShift Lightspeed Operator.
-
You have
ocorkubectlCLI access to the cluster. -
You have exposed the
lightspeed-app-serverservice by using an OpenShift route. -
You have the
ols-userClusterRole.
2.4.1. Authenticate with the API
To interact with the OpenShift Lightspeed API, you must use token-based authentication. The Service validates your identity through a Kubernetes TokenReview and SubjectAccessReview (SAR) against the /ols-access URL. Every request must include a valid OpenShift bearer token in the Authorization header.
Procedure
Grant the
ols-userrole by using any of the following code:To the user:
oc adm policy add-cluster-role-to-user ols-user _<username>_To the Service account:
oc adm policy add-cluster-role-to-user ols-user \ system:serviceaccount:_<namespace>_:_<service_account_name>_
Obtain a bearer token for your authentication method by any of the following ways:
For your own user:
TOKEN=$(oc whoami -t)For a Service account:
TOKEN=$(oc create token <service_account_name> -n <namespace>)
Verification
Confirm the token is valid by querying the
/authorizedendpoint:curl -k -X POST "https://${OLS_HOST}/authorized" \ -H "Authorization: Bearer ${TOKEN}"
2.4.2. OpenShift Lightspeed API endpoints reference
The following versioned endpoints allow you to interact with the Service, manage conversation history, and submit user feedback.
| Endpoint | Description |
|---|---|
|
|
Sends a prompt to the LLM. Required field: |
|
|
Delivers responses as a server-sent events (SSE) stream. Supports types: |
|
| Lists conversation IDs, summaries, and message counts for the user. |
|
| Retrieves history for a specific conversation. |
|
| Deletes a specific conversation history. |
|
|
Submits sentiment ( |
2.4.3. Supported attachment formats
To provide extra context such as logs or configurations, you must include an attachments array in the POST /v1/query request body.
| Attachment type | Details |
|---|---|
| Logs |
Use the |
| Configurations |
Use the |
2.4.4. OpenShift Lightspeed API error handling
The OpenShift Lightspeed API returns JSON objects that contain a detail field with a response and a cause.
| Status code | Description |
|---|---|
| 401 | Unauthorized. The request is missing a token or the token is invalid. |
| 403 |
Forbidden. The user lacks the |
| 413 | Payload too large. The prompt exceeds the large language model (LLM) context window. |
| 503 | Service unavailable. The Service or LLM is still initializing. |
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}