Skip to content

docs: document bearer JWT auth on the journey ingest endpoint #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document bearer JWT auth on the journey ingest endpoint #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion sales-copilot/introduction.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Sales CoPilot by Demand IQ lets you build AI-narrated sales presentations with i

## Authentication

Most API endpoints require a session cookie obtained from `POST /api/auth/login`. Presentation playback endpoints (`/api/qa`, `/api/narration/*`) also accept a `presentationId` for unauthenticated viewer access. Appointment and event tracking endpoints use an HMAC-signed presentation token passed via the `x-presentation-token` header.
Most API endpoints require a session cookie obtained from `POST /api/auth/login`. The journey ingest endpoint (`POST /api/decks/{deckId}/ingest`) additionally accepts a Bearer JWT in the `Authorization` header for server-to-server callers that don't run in a browser session. Presentation playback endpoints (`/api/qa`, `/api/narration/*`) also accept a `presentationId` for unauthenticated viewer access. Appointment and event tracking endpoints use an HMAC-signed presentation token passed via the `x-presentation-token` header.

For portal integrations, Sales CoPilot supports SSO via `GET /api/auth/sso?code={authCode}`. The portal redirects users with a short-lived authorization code that is exchanged for an access token server-side. Pass `embedded=1` when running inside an iframe and an optional `theme` parameter (`light` or `dark`) to match the portal appearance on first render. In production, set the `APP_URL` environment variable to the public base URL so that SSO redirects resolve correctly behind a load balancer.

Expand Down
13 changes: 11 additions & 2 deletions sales-copilot/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,12 @@
"in": "cookie",
"name": "session",
"description": "Session cookie obtained from `POST /api/auth/login`."
},
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "Bearer token for server-to-server (M2M) callers, passed as `Authorization: Bearer <token>`. Accepted on the journey ingest endpoint for backend services dispatching journey completions. Use a session cookie for browser-based integrations."
}
},
"schemas": {
Expand Down Expand Up @@ -2895,10 +2901,13 @@
"Ingest"
],
"summary": "Ingest a journey completion",
"description": "Creates a personalized presentation from a Demand IQ journey completion event. Pass the prospect identifier and the upstream event ID; Sales CoPilot fetches the authoritative homeowner, pricing, and product data from the Core API and provisions a presentation against the specified deck.\n\n**Idempotency**: a duplicate `source_event_id` for the same deck returns the existing `presentation_id` without creating a new presentation or sending any email.\n\n**Delivery**: if delivery is enabled on the deck, the presentation link is emailed to the homeowner automatically. The `send_status` field reports the outcome.",
"description": "Creates a personalized presentation from a Demand IQ journey completion event. Pass the prospect identifier and the upstream event ID; Sales CoPilot fetches the authoritative homeowner, pricing, and product data from the Core API and provisions a presentation against the specified deck.\n\n**Authentication**: accepts either a session cookie (browser/portal integrations) or a Bearer JWT (server-to-server integrations). Server-to-server callers are treated as trusted system principals and may ingest into any deck by UUID; session-authenticated callers can only ingest into decks owned by their organization.\n\n**Idempotency**: a duplicate `source_event_id` for the same deck returns the existing `presentation_id` without creating a new presentation or sending any email.\n\n**Delivery**: if delivery is enabled on the deck, the presentation link is emailed to the homeowner automatically. The `send_status` field reports the outcome.",
"security": [
{
"sessionCookie": []
},
{
"bearerAuth": []
}
],
"parameters": [
Expand Down Expand Up @@ -2993,7 +3002,7 @@
}
},
"404": {
"description": "Deck not found for the authenticated tenant.",
"description": "Deck not found. For session-authenticated callers, this is also returned when the deck is not owned by the caller's organization.",
"content": {
"application/json": {
"schema": {
Expand Down