Permissions

The API applies the same rules as the admin. A token may do through the API exactly what its owner may do in the admin: no more, and, for a read-only token, less.

Every request is checked in three steps:

1. The token's scope. Does this token read only, or may it also write? See Authentication.
2. The owner's roles. May this person or service account use this kind of endpoint at all?
3. The record. May they see or change this particular offer, account or application? The same checks decide this as in the admin, for example whether an organiser may still edit an offer that is already published.

Roles and endpoints

Admins pass every ROLE_HOST check, and super admins pass every check. For other admins the roles for participants and payments are separate: an admin without Teilnehmer:innen can't use the participant endpoints, and one without Zahlungen can't see receipts.

A request that fails the role check gets 403 Forbidden.

What organiser users see

Organiser users (ROLE_HOST without ROLE_ADMIN) see their own part of the programme, just like in the admin:

• Offers of the organisers they belong to, plus any offer that was shared with them directly. Nothing else, not even the published offers of other organisers: for those, call the API without a token. They can create and copy offers while the edition's editing phase is open, and change their offers (and refill their waiting lists) until they are reviewed or published. They can take offers through publication only if the edition allows organisers to publish.
• Organisers they are a member of. They can change those, but can't create or delete organisers.
• Invitations into the teams of their organisers. They can invite colleagues, send invitations again and withdraw them.
• Applications to their offers, but only once the edition has released the participant lists, and only until the data retention period after the offer has ended. They always have to name the offer (?offer= or /offers/{uuid}/attendances). Whether they can confirm, waitlist, change or move applications to another offer depends on how the installation is configured; creating and withdrawing applications is left to admins.
• Search results limited to their own offers and organisers.

Not found means "not found, or not yours"

When you ask for a single record you may not see, the API answers 404 Not Found, not 403. It doesn't confirm that the record exists. The message says so:

{
  "type": "/errors/404",
  "title": "An error occurred",
  "status": 404,
  "detail": "No offer with this identifier, or none you may see."
}

Lists simply leave out the records you may not see. The one exception is an offer's participant list: if you may not see it yet, the answer is 403.

Masked personal data

On installations that host several municipalities, global admins see another municipality's people only through a support disclosure, and even then perhaps only their names, not their contact details. The API follows the same rules. Records whose personal data you may not see carry "piiMasked": true:

• If you may not see the person at all, names, e-mail, phone numbers and addresses are left out, and references to them contain only the uuid.
• If you may see the identity but not the contact details, the name is included but e-mail, phone numbers and addresses are left out.

{
  "uuid": "0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05",
  "roles": ["ROLE_MEMBER"],
  "participants": [{ "uuid": "0191c7b3-1f2a-7c4d-8e5f-6a7b8c9d0e06" }],
  "piiMasked": true
}

Within your own municipality you see everything your roles allow, and piiMasked is false.