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.

The Info directory excludes demo groups (kind=demo). Public access by their identifier and their presence in the screen directory are preserved.

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.

map-sources¶

Map source — an external layer the Pysae applications draw on their maps: aerial imagery from IGN or Esri, a local authority's map or data, served in XYZ, WMTS, WMS or WFS. Applications call the provider directly; the API only describes the source.

Identifier <key>, a slug such as esri-world-imagery. Pysae declares a catalogue every group inherits; a group overrides a source field by field, or declares sources of its own. The merged read gives each source its origin, its status — disabled, missing key or ready — and, when ready, the MapLibre source to add to the map and a tile URL to test the key from the browser. tags let an application match its layer buttons with the sources, and app keeps the sources a given application can offer.