Cargo A/C
Integration

API Reference

The api.cargo.ac identity contract — the shared endpoints sibling surfaces call to verify tokens, provision identities and read the app registry.

Base URLhttps://api.cargo.ac/v1

Authentication

POST
/auth/verifyService key
stable

Verify a cargo.ac JWT and return the resolved identity + roles.

Request

  • tokenstring— The cargo.ac-issued access token to validate.

Response

  • validboolean— Whether the token is authentic and unexpired.
  • user_iduuid— The subject's stable identity id.
  • rolesstring[]— App roles granted to the subject.
GET
/auth/sessionBearer token
stable

Resolve the current bearer session into a profile snapshot.

Response

  • user_iduuid— The signed-in identity id.
  • emailstring— Primary email address.
  • user_type'internal' | 'client'— Identity segmentation.

Provisioning

POST
/identitiesService key
beta

Provision (or upsert) an identity from a trusted spoke.

Request

  • emailstring— Email address for the new identity.
  • full_namestring— Display name.
  • user_type'internal' | 'client'— Segmentation for the identity.

Response

  • user_iduuid— The created or matched identity id.
  • createdboolean— True if a new identity was created.
POST
/identities/{user_id}/enrollmentsService key
beta

Enroll an identity into a registered application.

Request

  • app_keystring— Registry key of the target application.
  • rolestring— Initial app role for the enrollment.

Response

  • enrollment_iduuid— The created enrollment record id.

Registry

GET
/appsBearer token
stable

Read the shared application registry served by cargo.ac.

Response

  • appsApp[]— Registered apps, consoles and websites.

Telemetry

POST
/apps/{app_key}/heartbeatService key
planned

Report spoke liveness + event counts back to the hub.

Request

  • versionstring— Deployed spoke version.
  • eventsEventCount[]— Signup/login/role-change counts since last beat.

Response

  • ackboolean— Whether the heartbeat was recorded.

This contract is dependency-free and lifts verbatim into the future standalone api.cargo.ac deployment and each spoke's client SDK.