Skip to main content

Authentication

All application endpoints under /api are protected. Requests must include a valid JSON Web Token (JWT) in the Authorization header using the Bearer scheme:

Authorization: Bearer <your_jwt_token>

The project_id claim​

Zyles is multi-tenant. Every JWT carries a project_id claim, and the backend scopes all data access to that project:

  • Leads, jobs, calls and other resources are only visible within their project.
  • Passing an ID that belongs to another project returns 401 Unauthorized, not 404 — the API does not reveal whether the resource exists elsewhere.

Because the project is taken from the token, you never pass project_id in request bodies — it is inferred server-side.

Obtaining a token​

Tokens are issued by the authentication endpoints (e.g. login / project selection). A typical flow:

  1. Log in with user credentials to obtain a user session.
  2. Select a project — this returns a JWT scoped to that project_id.
  3. Use that JWT as the Bearer token for all subsequent API calls.
tip

For local testing there is a mint_token helper in the backend repo (mint_token.py) that issues a signed JWT for a given project. Use it only against non-production environments.

Example request​

curl -X POST https://backend.zyles.ai/api/leads/add \
  -H "Authorization: Bearer $ZYLES_JWT" \
  -H "Content-Type: application/json" \
  -d '[{"first_name":"John","last_name":"Doe","phone_number":"+49123456789"}]'

Missing or invalid token​

If the header is absent, malformed, or the token has expired, the endpoint returns an error envelope with success: false:

{
  "success": false,
  "message": "Authorization header missing"
}
{
  "success": false,
  "message": "Invalid or expired authentication token"
}

See Errors & conventions for the full error model.