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 attendance? The same checks decide this as in the admin, for example whether a host user 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.

ROLE_PARTICIPANTS_ADMIN, ROLE_PAYMENTS_ADMIN and ROLE_CMS_ADMIN count only next to ROLE_ADMIN or ROLE_SUPER_ADMIN, for a colleague as for a service account. On any other account they grant nothing. Without ROLE_PARTICIPANTS_ADMIN, an account names its participants by uuid only; without ROLE_PAYMENTS_ADMIN, or while the app Zahlungen is switched off, it has no debtor. The role alone does not open the debtors then.

A request that fails the role check gets 403 Forbidden.

What host users see

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

• Offers of the hosts they are a member of, plus any offer that was shared with them directly. Nothing else, not even the published offers of other hosts: for those, call the API without a token. They can create and copy offers while the edition's host_editing_stage task is active. While it is active, they can also change their offers (and refill their waitlists) and delete offers without attendances, until the offers are reviewed or published. They can take offers through publication only if the edition allows hosts to publish.
• Hosts they are a member of. They can change those, but can't create or delete hosts.
• Host invitations into their hosts. They can invite colleagues, send invitations again and withdraw them.
• Attendances for their offers, but only while the edition's publish_lists task is active. If that task is alwaysActive, only until the data retention period after the offer's last date has passed. They always have to name the offer (?offer= or /offers/{uuid}/attendances). Where the edition asks hosts to sign a confidentiality declaration, they see none before they signed it. They see the attendances their participant list in the admin shows them, which depends on the edition and the installation; List an offer's participants has the rules. Whether they can confirm, waitlist, change or move attendances to another offer depends on how the installation is configured; creating and withdrawing attendances is left to admins.
• Search results limited to their own offers and hosts.

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, or not before you signed the edition's confidentiality declaration, the answer is 403.

Masked personal data

On installations that host several tenants, global admins don't see the personal data of every tenant's people. The API follows the same rules as the admin. 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 tenant you see everything your roles allow, and piiMasked is false.

A receipt with "piiMasked": true is read-only. Paying or abandoning, reversing and adjusting it is refused with 403, and so is creating a receipt for a family whose details you read masked.

Outside your own tenant, searches find no people, because a hit would reveal what a masked value says:

• q finds nothing on accounts, participants and debtors, and neither does email on accounts.
• q on receipts searches the receipt number only.
• account as an e-mail address finds nothing; a UUID still works.
• GET /search returns no participants and no accounts, and receipts by number only.
• The lists of accounts, participants and debtors are ordered by creation, not by name.