Project scope

Project scope is for B2B and B2B2C operators: companies who want to embed Juglans agents into their own product and serve their own end-users. Where agent scope is "I am one agent", project scope is "I am a company calling on behalf of one of my users".

Prerequisites. You need at least one agent before this is useful — create one via the UI or POST /api/agents (covered in Account & Platform). The project owner must own the agents they want to attach to a project.

The B2B2C model

        +---------------------+
        |  Project owner      |   Owner JWT
        |  (you, the company) |   (control plane: CRUD, settings, members)
        +---------+-----------+
                  |
                  | mints
                  v
        +---------------------+
        |  Project API key    |   jg_p_*
        |  jg_p_a1b2c3d4...   |   (runtime: SDK from your backend)
        +---------+-----------+
                  |
                  | called with optional X-USER-ID header
                  v
        +---------------------+
        |  Your end-users     |   shadow `external_user` records
        |  alice / bob / ...  |   auto-created on first use
        +---------------------+

A project owns agents (use-rights only — the agent itself stays under its creator's account), humans (collaborators you invited), and external users (your end-users, identified by whatever ID you send in the X-USER-ID header). Conversations are partitioned by (project, external_user), so the same project key serving Alice and Bob never crosses streams. The same partition flows through to the agent runtime's per-thread state via the chat_id it sees. Audit-log partitioning by external user is on the roadmap — today's audit_log is agent-scope only.

Minting a project key is documented in Webhooks & Rate Limits (endpoint) and surfaced in the dashboard under API → API keys.

Where things live in the dashboard

Project configuration is split across three sidebar tabs. Most developer setup happens in API, which has its own sub-tabs:

Sidebar tab	Purpose
Members	Add agents to the project, invite humans, list / offboard end-users (read-only view available under API → Webhooks & users too).
API	Developer center. Five sub-tabs:
→ Quickstart	Onboarding cards + 30-second curl. Persistent info bar at the top shows Project ID, Base URL, and Auth header on every sub-tab.
→ API keys	Mint, list, revoke `jg_p_*` project keys. Plaintext is shown exactly once.
→ Embed	Configure the chat widget that drops into your site — default agent, allowed origins, identity verification HMAC, theme.
→ Webhooks & users	Outbound webhook URL + signing secret + per-project rate limit. List of end-users (X-USER-ID shadow rows).
→ Reference	Three principal types explained side-by-side, endpoint table, SDK snippets (TypeScript / Python / OpenAI-compat).
Settings	Project name, description, deletion. Cosmetic-only.

Tabs are URL-addressable — e.g. /app/project/api?tab=embed deep-links to the embed sub-tab so you can share a link in your team chat.

How this differs from agent scope

	Agent scope	Project scope
Bearer prefix	`jg_a_*`	`jg_p_*`
Principal	One agent	A project (which contains many agents)
End-user partitioning	None — the key is the agent	`X-USER-ID` header per call
Owner mode	n/a — agent is its own thing	Owner JWT for control plane
Endpoints	`/api/me`, `/mcp`, `/api/llm/...`, `/api/memory`, `/api/orders`	`/api/projects/{id}/...`

If you only need a single agent for yourself, use agent scope. If you need to fan out one agent (or a small fleet) to your own user base, you want this chapter.

What's in this chapter

Authentication — owner JWT vs project key vs project key + X-USER-ID. Header reference, revocation semantics.
Conversations — multi-thread chat, SSE streaming, per-end-user partitioning.
Invites and members — adding agents to a project, inviting human collaborators by email.
External users — listing and force-offboarding your end-users.
Webhooks and rate limits — project settings, signing-secret rotation, project API key minting/revocation.
Channels — WeChat / IM bot bindings.
Reference — compact endpoint table.

Base URLs

Production: https://api.juglans.ai
Local dev: http://localhost:3002