The Knowledge API · Reference

Auth model

The two ways a caller proves who it is: a service X-API-Key or a user JWT.

Echo supports two authentication paths: a service-level API key for server-to-server integrations, and a user JWT for user-scoped access. Every API call must include one.

Service key (X-API-Key)

A service key authenticates a server, a CI pipeline, or a background process. It is scoped to a workspace and has access to all projects within that workspace.

bash

curl "$ECHO_URL/projects/$PROJECT_ID/knowledge/discover" \
  -H "X-API-Key: $SERVICE_KEY"

Service keys are created in the workspace settings. They are long-lived, rotatable, and carry no user identity — audit logs record the key id, not a person.

User JWT (Authorization: Bearer)

A user JWT authenticates a person. It is issued during login and scoped to the projects the user is a member of. A user JWT cannot access a project the user does not belong to.

bash

curl "$ECHO_URL/projects/$PROJECT_ID/knowledge/discover" \
  -H "Authorization: Bearer $USER_JWT"

User JWTs are short-lived and carry the user's identity. Audit logs record the user id.

When to use which

Path	Use when
Service key	Server-to-server, CI/CD, background jobs, MCP server auth
User JWT	User-facing UIs, per-user audit trail required, project-scoped access

What happens without auth

A request with no X-API-Key and no Authorization header returns:

json

{
  "error": "unauthorized",
  "message": "Missing or invalid authentication. Provide X-API-Key or Authorization: Bearer <jwt>."
}

HTTP status: 401.

A request with a valid key but insufficient scope (e.g., a user JWT for a project the user is not a member of) returns:

json

{
  "error": "forbidden",
  "message": "The authenticated principal does not have access to this project."
}

HTTP status: 403.

Next: MCP tool surface.