Organization¶

These entities answer two questions asked before any call: which perimeter it applies to, and on whose behalf.

groups¶

Group — the operated network. It is the API's isolation unit: every other entity belongs to a group, and a piece of data never exists outside its own. An operator running several networks has one group per network.

Identifier <group_id>, present in the path of nearly every endpoint. The group holds its configuration — published GTFS, operating options, passenger information settings — on which the entities it contains depend.

Groups are managed from the Pysae applications; their endpoints are not published in the public spec, an integrator working on a group that has been communicated to them.

teams¶

Team — a subdivision of the group, used to partition operations: a depot, a geographic area, a subcontractor. Drivers and vehicles are attached to it, and a user may only have access to the data of certain teams.

Identifier <team_id>. The attachment is multiple: a driver, like a vehicle, carries a list of teams.

users¶

User — a human account accessing the group, typically a dispatcher or an operations manager. Not to be confused with the driver, who is not a user: they identify themselves on the Pysae Driver app, not on the operations interface.

Identifier <user_id>. A user may belong to several groups, with a role specific to each.

roles¶

Role — a user's access level on a given group. It governs which endpoints can be called and which data is visible; a role restricted to certain teams only sees their drivers and vehicles.

A role has no identifier of its own: it links a user to a group, and is therefore handled through <user_id>.

api-keys¶

API key — a persistent, revocable credential intended for automated integrations. This is the recommended mechanism to call the API from a third-party system, rather than a session opened with a password.

Identifier <api_key_id>. A key is attached to exactly one principal — a user, a device or a role — and can be restricted by scope and expiry date. A key may span several groups.

Creating a key and using it in a request are detailed on the Authentication page.