cabgo
InicioAcceder

Cabgo API — guía de auth

OAuth 2.0 + scope catalog + permisos. Esta página explica cómo autenticarse contra la API; para la referencia interactiva con ejemplos curl / JS / Python y consola try-it-out usa /api-docs.

→ Referencia interactivaOpenAPI 3.1 (JSON)Markdown para LLMs

Empezando

La API expone dos niveles de acceso:

  • Operador (audience=dashboard): scopes tenant.* mapeados a los permisos de MembershipPermission. Una pérdida de permiso en el dashboard invalida el scope correspondiente en tiempo real.
  • Usuario final (audience=rider o driver): scopes rider.* / driver.* condicionados a los flags de tenant (taxiEnabled, deliveryEnabled). Si un operador desactiva delivery, los tokens existentes con rider.orders:create dejan de funcionar inmediatamente.

Discovery

Flujo authorization_code + PKCE

  1. Registra tu cliente vía POST /oauth/register con tus redirect URIs. Para apps públicas (CLI, desktop) usa token_endpoint_auth_method=none + PKCE obligatorio.
  2. Genera code_verifier + code_challenge (S256) y redirige al usuario a https://www.cabgo.app/oauth/authorize. Para tokens rider/driver pasatenant_hint=<slug>.
  3. Tu redirect URI recibe ?code=...&state=.... Intercambia inmediatamente por tokens vía POST /oauth/token congrant_type=authorization_code + code_verifier.
  4. Llama /api/v1/* con Authorization: Bearer <access_token>. Verifica offline contra JWKS — sin round-trips al issuer.
  5. Cuando el access token expira, intercambia el refresh_token por uno fresco. La rotación es obligatoria — si reutilizas un refresh ya consumido, toda la cadena de tokens del par (cliente, actor) queda revocada.

Scopes

OIDC (compat)

ScopeDescripciónRequiere
openidOIDC authentication—
profileRead profile claims—
emailRead email claim—

Operador — audience=dashboard

ScopeDescripciónRequiere
tenant.trips:readList and read trips for the tenantPermission: VIEW_TRIPS
tenant.trips:writeCreate and update trips for the tenantPermission: CREATE_TRIPS
tenant.trips:deleteDelete trips for the tenantPermission: DELETE_TRIPS
tenant.drivers:readList and read driver profilesPermission: VIEW_DRIVERS
tenant.drivers:writeCreate and update driversPermission: CREATE_DRIVERS
tenant.customers:readList and read customer profilesPermission: VIEW_CUSTOMERS
tenant.customers:writeCreate and update customersPermission: CREATE_CUSTOMERS
tenant.settings:readRead tenant settings (pricing, zones, services)Permission: VIEW_SETTINGS
tenant.settings:writeUpdate tenant settingsPermission: EDIT_SETTINGS
tenant.reports:readRead reports and analyticsPermission: VIEW_REPORTS
tenant.reports:exportExport reportsPermission: EXPORT_REPORTS
tenant.businesses:readList businesses (delivery module)Permission: VIEW_BUSINESSES
tenant.businesses:writeCreate and update businessesPermission: MANAGE_BUSINESSES
tenant.delivery:readList food ordersPermission: VIEW_FOOD_ORDERS
tenant.delivery:writeUpdate food ordersPermission: MANAGE_FOOD_ORDERS
tenant.wallets:readRead driver / customer wallet balancesPermission: VIEW_WALLETS
tenant.wallets:writeAdjust wallets and approve withdrawalsPermission: MANAGE_WALLETS
tenant.branding:writeUpdate branding (logos, colors, copy)Permission: EDIT_BRANDING

Rider — audience=rider

ScopeDescripciónRequiere
rider.profile:readRead your profile—
rider.profile:writeUpdate your profile—
rider.trips:readRead your trips—
rider.trips:createRequest a rideTenant flag: taxiEnabled
rider.trips:cancelCancel a trip you requested—
rider.orders:readRead your delivery ordersTenant flag: deliveryEnabled
rider.orders:createPlace a delivery orderTenant flag: deliveryEnabled
rider.addresses:writeManage your saved addresses—
rider.payments:readList your payment methods—
rider.wallet:readRead your wallet balance—

Driver — audience=driver

ScopeDescripciónRequiere
driver.profile:readRead your driver profile—
driver.status:writeGo online or offline—
driver.trips:readRead your assigned trips—
driver.trips:acceptAccept incoming ride offers—
driver.trips:completeMark trips as arrived / started / completed—
driver.wallet:readRead your earnings and wallet—
driver.documents:readRead the status of your uploaded documents—

Endpoints

MétodoPathScopesPermiso / FeatureResumen
GET/api/v1/merider.profile:readdriver.profile:read—Read your profile
GET/api/v1/tripstenant.trips:readVIEW_TRIPSList tenant trips
GET/api/v1/trips/{id}tenant.trips:readVIEW_TRIPSRead a single trip
GET/api/v1/driverstenant.drivers:readVIEW_DRIVERSList tenant drivers
GET/api/v1/customerstenant.customers:readVIEW_CUSTOMERSList + search customers
GET/api/v1/settingstenant.settings:readVIEW_SETTINGSRead tenant settings
GET/api/v1/servicestenant.settings:readVIEW_SETTINGSList tenant service types
GET/api/v1/zonestenant.settings:readVIEW_SETTINGSList dispatch zones
GET/api/v1/brandingtenant.settings:readVIEW_BRANDINGRead tenant branding
PATCH/api/v1/brandingtenant.branding:writeEDIT_BRANDINGUpdate tenant branding
GET/api/v1/reports/summarytenant.reports:readVIEW_REPORTSTenant KPI summary
GET/api/v1/walletstenant.wallets:readVIEW_WALLETSRead wallet totals
GET/api/v1/businessestenant.businesses:readVIEW_BUSINESSESList delivery businesses
GET/api/v1/orderstenant.delivery:readVIEW_FOOD_ORDERSList delivery orders
GET/api/v1/me/tripsrider.trips:readdriver.trips:read—List your trips
POST/api/v1/me/tripsrider.trips:createtaxiEnabledRequest a ride
POST/api/v1/me/trips/{id}/cancelrider.trips:cancel—Cancel your trip
GET/api/v1/me/addressesrider.profile:read—List saved addresses
POST/api/v1/me/addressesrider.addresses:write—Save a new address
GET/api/v1/me/walletrider.wallet:readdriver.wallet:read—Read your wallet balance
GET/api/v1/me/payment-methodsrider.payments:read—List saved payment methods
GET/api/v1/me/ordersrider.orders:readdeliveryEnabledList your delivery orders
PATCH/api/v1/me/statusdriver.status:write—Update driver status
POST/api/v1/me/trips/{id}/acceptdriver.trips:accept—Accept an open trip
POST/api/v1/me/trips/{id}/arriveddriver.trips:complete—Mark as arrived at pickup
POST/api/v1/me/trips/{id}/startdriver.trips:complete—Start the trip
POST/api/v1/me/trips/{id}/completedriver.trips:complete—Complete the trip

Errores estándar

  • 401 unauthorized — token ausente, inválido o revocado. Header WWW-Authenticate: Bearer ....
  • 403 insufficient_scope — el token no tiene los scopes que el endpoint requiere. Header WWW-Authenticate: Bearer error="insufficient_scope".
  • 403 forbidden — operador perdió el Permission requerido.
  • 403 feature_disabled — el tenant tiene la feature requerida apagada. Cuerpo incluye feature.

SDK / MCP

El paquete oficial cabgo-mcp implementa el flujo OAuth completo + expone cada endpoint como tool MCP para Claude Desktop, Cursor, Continue y otros clientes. Instalación y configuración en /docs/api/mcp.