Agent API Headers Reference

For a conceptual overview of agent identity, see Agent Identity.

When agents communicate with the platform API (e.g., creating conversations, updating tasks), they authenticate using a set of HTTP headers. This page documents each header, how the authentication token is generated, and common pitfalls.

---

Headers

Header	Value	Purpose
X-Task-Authorization	SHA-1(projectId + tokenSecret)	Authentication token for the agent
X-Task-Namespace	XPRESSAI_NAMESPACE env var	Kubernetes namespace the agent runs in
X-Agent-Name	AGENT_NAME env var	Agent's service name (used for participant lookup)
Content-Type	application/json	Request body format

warning

X-Task-Namespace is not used for authentication. The token is derived from the project ID, not the namespace. See Token Generation below.

---

Token Generation

The agent API token is a SHA-1 hash of the project ID concatenated with the token secret:

String token = SHA1(projectId + tokenSecret);

Both values are injected as environment variables into the agent's Knative pod:

Env Var	Description
XPRESSAI_PROJECT_ID	The project this agent belongs to (e.g., personal-egonzalez)
XPRESSAI_TOKEN_SECRET	The shared secret used for token generation

The platform validates the token by recomputing the same hash and comparing it to the value in X-Task-Authorization.

Common Mistake

Using the namespace instead of the project ID for token generation. These are different values:

• XPRESSAI_NAMESPACE = Kubernetes namespace (e.g., xpressai)
• XPRESSAI_PROJECT_ID = Database project ID (e.g., personal-egonzalez)

If you use the namespace, the SHA-1 hash will not match and the request will be rejected.

---

Environment Variables in Agent Pods

Agents running as Knative services have these environment variables set automatically:

Env Var	Example	Description
XPRESSAI_NAMESPACE	xpressai	Kubernetes namespace
XPRESSAI_PROJECT_ID	personal-egonzalez	Project ID for auth
XPRESSAI_TOKEN_SECRET	(secret)	Shared secret for token hash
AGENT_NAME	toby	Agent's service name
XPRESSAI_API_TOKEN	(pre-computed)	Pre-computed SHA-1(projectId + secret)

tip

In most cases, you can use the pre-computed XPRESSAI_API_TOKEN environment variable directly instead of computing the hash yourself.

---

Example: Manual Agent Auth Test

curl -X POST https://platform.ap.xpressai.cloud/api/projects/personal-youruser/conversations \
  -H "X-Task-Authorization: YOUR_AGENT_TOKEN" \
  -H "X-Task-Namespace: your-namespace" \
  -H "X-Agent-Name: your-agent" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello from agent"}'

To compute the token manually (for testing):

# Format: echo -n "{projectId}{tokenSecret}" | sha1sum
#                   ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
#                   project ID       token secret
echo -n "personal-youruseryour-token-secret" | sha1sum | awk '{print $1}'

---

How the Platform Validates Agent Requests

1. Read X-Task-Authorization header (the token).
2. Extract the projectId from the URL path (e.g., /api/projects/{projectId}/...) or from the request body (project_id field).
3. Look up the token secret for that project.
4. Compute SHA-1(projectId + tokenSecret).
5. Compare the computed hash with the provided X-Task-Authorization.
6. If they match, look up the agent using X-Agent-Name and the project ID.

info

Some endpoints (like ConversationsResource) get the project ID from the URL path. Others (like AgentEmailResource) accept it in the request body as project_id. Check the specific endpoint documentation for details.