iblai /iblai-vibe-crm-overview
Reference skill for the ibl.ai CRM. Covers authentication, seeded
defaults, the four CRM RBAC roles, and indexes the CRM workflow skills
— the crm-* skills in the DM skill set (iblai-dm-pro/.claude/skills/).
This skill builds no UI — open it first when you need orientation, then
jump to the workflow skill that matches the surface you are building.
Common setup (brand, conventions, env files, verification): see docs/skill-setup.md.
Authentication
Every CRM endpoint lives under /api/crm/ and requires a
Platform-scoped token:
Authorization: Token <your-access-token>
Tokens bind to exactly one Platform at the moment of issue. The
Platform is inferred from the token on every request — there is no
?platform_key= query parameter on the consumer surface, and supplying
one will not change the Platform a request resolves to.
Records belonging to a different Platform return 404 Not Found,
never 403 Forbidden. This is intentional: returning 403 would
leak the existence of cross-Platform records. Treat a 404 on a
record you just created as a sign you are pointing at the wrong
Platform; a 403 always means "authenticated but the role does not
grant this action."
The full REST contract (base URL, pagination envelope, ID types per
resource, side effects) is in
references/api-overview.md. For
token wiring inside a Next.js app see /iblai-vibe-auth.
Seeded defaults
The first time a Platform is provisioned, the CRM seeds a working configuration. You do not need to create any of these yourself — they exist on every Platform and back-fill into existing Platforms via a data migration.
- One default Pipeline with
code="default",is_default=true,rotten_days=30. - Six default Stages on that Pipeline, referenced by stable
code:new→qualified→proposal→negotiation→won(terminal,is_won=true) andlost(terminal,is_lost=true). - Four default Lead Sources:
web,referral,cold_call,advertisement.
The stage and lead-source code fields are stable across environments
(dev / staging / prod) and across renames. Numeric id values are not
— always reference seeds by code in client code, save the pipeline
id only for the immediate deal payload.
Full seeded tables (every stage's probability / sort_order /
terminal flags, every lead source name) are in
references/seeded-defaults.md.
RBAC
The CRM ships four roles per Platform. Roles are seeded automatically on Platform provisioning and assigned through the standard role-management surface — the CRM does not expose its own role-assignment endpoints. A user may hold more than one role; effective permissions are the union.
| Role | One-line mandate |
|---|---|
| CRM Viewer | Read everything across the CRM. Write nothing. |
| CRM User | Day-to-day operator — full CRUD on people, organizations, deals, activities, tags. Pipelines are read-only. No invitations. |
| CRM Manager | Wildcard CRM access — pipeline / stage / lead-source administration plus invitations. |
| CRM Inviter | Narrow role — read people and send invitations only. Cannot edit or create people. |
Two non-obvious rules worth a second look:
- Invitation is its own bucket.
Ibl.CRM/Persons/writedoes not implyIbl.CRM/Invite/action. Gate the "Invite" affordance independently. - Tag attach/detach requires
Ibl.CRM/Tags/write. A role withIbl.CRM/Persons/writecannot tag a person without it.
Full HTTP-verb → action-code mapping and the action-by-action matrix
are in references/rbac-matrix.md. For
the management UI that lists and binds roles, see /iblai-vibe-rbac.
The CRM skill family
The CRM workflow skills live in the DM skill set
(iblai-dm-pro/.claude/skills/), named crm-* — this
iblai-vibe-crm-overview skill is the index. Read crm-foundation
first, then pick the skill that matches the surface you are building.
| Skill | Covers |
|---|---|
crm-foundation |
Read first — auth, Platform scoping, pagination envelope, error model, the four RBAC roles + Ibl.CRM/* verbs, the three CRM notification types (CRM_PERSON_CREATED, CRM_DEAL_STAGE_CHANGED, CRM_PERSON_LINKED_TO_USER), the metadata escape hatch, and the cross-cutting tagging pattern |
crm-contacts |
Person + Organization CRUD, list filters (lifecycle stage / owner / organization / date / tags), tag attach / detach |
crm-person-onboarding |
Person lifecycle — /link-user/, /invite/, /merge/, the dedup triage (link vs invite vs merge), and the separate Ibl.CRM/Invite/action bucket |
crm-pipeline |
Pipelines, Stages, Lead Sources, Deals CRUD + the deal state machine (/move-stage/, /won/, /lost/), kanban fetch, Deal tag attach / detach |
crm-activities |
Activity CRUD, the /done/ action, schedule + reminder fields, and the timeline (incl. auto-Activities from Deal stage transitions) |
crm-tags |
Tag CRUD, hex-color contract, name uniqueness per Platform, cascade delete, attach / detach convention |
When in doubt, start with crm-contacts (a deal needs a person), then
crm-pipeline, then layer crm-activities and crm-tags on the detail
pages. CRM notifications are covered in crm-foundation.
Related skills
crm-foundation— auth, pagination, RBAC, notifications, tagging (read first)crm-contacts— People + Organizations + list filterscrm-person-onboarding— link / invite / merge + dedup triagecrm-pipeline— Pipelines + Stages + Lead Sources + Dealscrm-activities— Activity timeline for persons and dealscrm-tags— Tag CRUD + attach / detach/iblai-vibe-auth— Token wiring; every CRM call uses the sameAuthorization: Token <token>header./iblai-vibe-rbac— Role-management UI (<Admin>→ Roles + Policies tabs) and the action-definitions endpoint. The four CRM roles are assigned here.- Brand guidelines: BRAND.md