CGM_Public/pretix_original
2
0
Fork 1
mirror of https://github.com/pretix/pretix.git synced 2026-05-03 14:54:04 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0e4727493e5105c08ca49e5971e30d9a6d8a8ea1
pretix_original/doc/api/resources/teams.rst
Raphael Michel df0b580dd6 Pluggable permissions (#5728) 
* Data model draft

* Refactor query and assignment usages of old permissions

* Backend UI

* API serializer

* Big string replace

* Docs, tests and fixes for teams api

* Update docs for device auth

* Eliminate old names

* Make tests pass

* Use new permissions, remove inconsistencies

* Add test for translations

* Show plugin permissions

* Add permission for seating plans

* Fix plugin activation

* Fix failing test

* Refactor to permission groups

* Update doc/api/resources/devices.rst

Co-authored-by: luelista <weller@rami.io>

* Update doc/api/resources/events.rst

Co-authored-by: luelista <weller@rami.io>

* Update src/pretix/api/serializers/organizer.py

Co-authored-by: luelista <weller@rami.io>

* Fix typo

* Fix python version compat

* Replacement after rebase

* Add proper permission handling for exports

* Docs for exporters

* Runtime linting of permission names

* Fix typos

* Show export page even without orders permission

* More legacy compat

* Do not strongly validate before plugins are loaded

* Rebase migration

* Add permission for outgoing mails

* Review notes

* Update doc/api/resources/teams.rst

Co-authored-by: Richard Schreiber <schreiber@pretix.eu>

* Clean up logic around exporters

* Review and failures

* Fix migration leading to forbidden combination

* Handle permissions on event copying

* Remove print-statements

* Make test clearer

* Review feedback

* Add AnyPermissionOf

* migration safety

---------

Co-authored-by: luelista <weller@rami.io>
Co-authored-by: Richard Schreiber <schreiber@pretix.eu>
2026-03-17 14:43:56 +01:00

739 lines
24 KiB
ReStructuredText
Raw Blame History

.. spelling:word-list:: fullname checkin
.. _`rest-teams`:
Teams
=====
.. warning:: Unlike our user interface, the team API **does** allow you to lock yourself out by deleting or modifying
the team your user or API key belongs to. Be careful around here!
Team resource
-------------
The team resource contains the following public fields:
.. rst-class:: rest-resource-table
===================================== ========================== =======================================================
Field Type Description
===================================== ========================== =======================================================
id integer Internal ID of the team
name string Team name
all_events boolean Whether this team has access to all events
limit_events list List of event slugs this team has access to
require_2fa boolean Whether members of this team are required to use
two-factor authentication
all_event_permissions bool Whether members of this team are granted all event-level
permissions, including future additions
limit_event_permissions list of strings The event-level permissions team members are granted
all_organizer_permissions bool Whether members of this team are granted all organizer-level
permissions, including future additions
all_organizer_permissions list of strings The organizer-level permissions team members are granted
can_create_events boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_change_teams boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_change_organizer_settings boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_manage_customers boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_manage_reusable_media boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_manage_gift_cards boolean **DEPRECATED**. Legacy interface, use ``limit_organizer_permissions``.
can_change_event_settings boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_change_items boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_view_orders boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_change_orders boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_view_vouchers boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_change_vouchers boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
can_checkin_orders boolean **DEPRECATED**. Legacy interface, use ``limit_event_permissions``.
===================================== ========================== =======================================================
Possible values for ``limit_organizer_permissions`` defined in the core pretix system (plugins might add more)::
organizer.events:create
organizer.settings.general:write
organizer.teams:write
organizer.seatingplans:write
organizer.giftcards:read
organizer.giftcards:write
organizer.customers:read
organizer.customers:write
organizer.reusablemedia:read
organizer.reusablemedia:write
organizer.devices:read
organizer.devices:write
organizer.outgoingmails:read
Possible values for ``limit_event_permissions`` defined in the core pretix system (plugins might add more)::
event.settings.general:write
event.settings.payment:write
event.settings.tax:write
event.settings.invoicing:write
event.subevents:write
event.items:write
event.orders:read
event.orders:write
event.orders:checkin
event.vouchers:read
event.vouchers:write
event:cancel
Team member resource
--------------------
The team member resource contains the following public fields:
.. rst-class:: rest-resource-table
===================================== ========================== =======================================================
Field Type Description
===================================== ========================== =======================================================
id integer Internal ID of the user
email string The user's email address
fullname string The user's full name (or ``null``)
require_2fa boolean Whether this user uses two-factor-authentication
===================================== ========================== =======================================================
Team invite resource
--------------------
The team invite resource contains the following public fields:
.. rst-class:: rest-resource-table
===================================== ========================== =======================================================
Field Type Description
===================================== ========================== =======================================================
id integer Internal ID of the invite
email string The invitee's email address
===================================== ========================== =======================================================
Team API token resource
-----------------------
The team API token resource contains the following public fields:
.. rst-class:: rest-resource-table
===================================== ========================== =======================================================
Field Type Description
===================================== ========================== =======================================================
id integer Internal ID of the invite
name string Name of this API token
active boolean Whether this API token is active (can never be set to
``true`` again once ``false``)
token string The actual API token. Will only be sent back during
token creation.
===================================== ========================== =======================================================
Team endpoints
--------------
.. http:get:: /api/v1/organizers/(organizer)/teams/
Returns a list of all teams within a given organizer.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"name": "Admin team",
"all_events": true,
"limit_events": [],
"require_2fa": true,
"all_event_permissions": true,
"limit_event_permissions": [],
"all_organizer_permissions": true,
"limit_organizer_permissions": [],
"can_create_events": true,
...
}
]
}
:query integer page: The page number in case of a multi-page result set, default is 1
:param organizer: The ``slug`` field of the organizer to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
.. http:get:: /api/v1/organizers/(organizer)/teams/(id)/
Returns information on one team, identified by its ID.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"name": "Admin team",
"all_events": true,
"limit_events": [],
"require_2fa": true,
"all_event_permissions": true,
"limit_event_permissions": [],
"all_organizer_permissions": true,
"limit_organizer_permissions": [],
"can_create_events": true,
...
}
:param organizer: The ``slug`` field of the organizer to fetch
:param id: The ``id`` field of the team to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
.. http:post:: /api/v1/organizers/(organizer)/teams/
Creates a new team
**Example request**:
.. sourcecode:: http
POST /api/v1/organizers/bigevents/teams/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
{
"name": "Admin team",
"all_events": true,
"limit_events": [],
"require_2fa": true,
"all_event_permissions": true,
"limit_event_permissions": [],
"all_organizer_permissions": true,
"limit_organizer_permissions": [],
...
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json
{
"id": 2,
"name": "Admin team",
"all_events": true,
"limit_events": [],
"require_2fa": true,
"all_event_permissions": true,
"limit_event_permissions": [],
"all_organizer_permissions": true,
"limit_organizer_permissions": [],
"can_create_events": true,
...
}
:param organizer: The ``slug`` field of the organizer to create a team for
:statuscode 201: no error
:statuscode 400: The team could not be created due to invalid submitted data.
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
.. http:patch:: /api/v1/organizers/(organizer)/teams/(id)/
Update a team. You can also use ``PUT`` instead of ``PATCH``. With ``PUT``, you have to provide all fields of
the resource, other fields will be reset to default. With ``PATCH``, you only need to provide the fields that you
want to change.
**Example request**:
.. sourcecode:: http
PATCH /api/v1/organizers/bigevents/teams/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 94
{
"all_organizer_permissions": false,
"limit_organizer_permissions": ["organizer.events:create"]
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"name": "Admin team",
"all_events": true,
"limit_events": [],
"require_2fa": true,
"all_event_permissions": true,
"limit_event_permissions": [],
"all_organizer_permissions": false,
"limit_organizer_permissions": ["organizer.events:create"],
"can_create_events": true,
...
}
:param organizer: The ``slug`` field of the organizer to modify
:param id: The ``id`` field of the team to modify
:statuscode 200: no error
:statuscode 400: The team could not be modified due to invalid submitted data
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
.. http:delete:: /api/v1/organizers/(organizer)/teams/(id)/
Deletes a team.
**Example request**:
.. sourcecode:: http
DELETE /api/v1/organizers/bigevents/teams/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 204 No Content
:param organizer: The ``slug`` field of the organizer to modify
:param id: The ``id`` field of the team to delete
:statuscode 204: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to change this resource.
Team member endpoints
---------------------
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/members/
Returns a list of all members of a team.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/members/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"fullname": "John Doe",
"email": "john@example.com",
"require_2fa": true
}
]
}
:query integer page: The page number in case of a multi-page result set, default is 1
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team does not exist
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/members/(id)/
Returns information on one team member, identified by their ID.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/members/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"fullname": "John Doe",
"email": "john@example.com",
"require_2fa": true
}
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:param id: The ``id`` field of the member to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team or member does not exist
.. http:delete:: /api/v1/organizers/(organizer)/teams/(team)/members/(id)/
Removes a member from the team.
**Example request**:
.. sourcecode:: http
DELETE /api/v1/organizers/bigevents/teams/1/members/1/ HTTP/1.1
Host: pretix.eu
**Example response**:
.. sourcecode:: http
HTTP/1.1 204 No Content
:param organizer: The ``slug`` field of the organizer to modify
:param team: The ``id`` field of the team to modify
:param id: The ``id`` field of the member to delete
:statuscode 204: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
:statuscode 404: The requested team or member does not exist
Team invite endpoints
---------------------
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/invites/
Returns a list of all invitations to a team.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/invites/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"email": "john@example.com"
}
]
}
:query integer page: The page number in case of a multi-page result set, default is 1
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team does not exist
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/invites/(id)/
Returns information on one invite, identified by its ID.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/invites/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"email": "john@example.org"
}
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:param id: The ``id`` field of the invite to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team or invite does not exist
.. http:post:: /api/v1/organizers/(organizer)/teams/(team)/invites/
Invites someone into the team. Note that if the user already has a pretix account, you will receive a response without
an ``id`` and instead of an invite being created, the user will be directly added to the team.
**Example request**:
.. sourcecode:: http
POST /api/v1/organizers/bigevents/teams/1/invites/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 94
{
"email": "mark@example.org"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json
{
"id": 1,
"email": "mark@example.org"
}
:param organizer: The ``slug`` field of the organizer to modify
:param team: The ``id`` field of the team to modify
:statuscode 204: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
:statuscode 404: The requested team does not exist
.. http:delete:: /api/v1/organizers/(organizer)/teams/(team)/invites/(id)/
Revokes an invite.
**Example request**:
.. sourcecode:: http
DELETE /api/v1/organizers/bigevents/teams/1/invites/1/ HTTP/1.1
Host: pretix.eu
**Example response**:
.. sourcecode:: http
HTTP/1.1 204 No Content
:param organizer: The ``slug`` field of the organizer to modify
:param team: The ``id`` field of the team to modify
:param id: The ``id`` field of the invite to delete
:statuscode 204: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
:statuscode 404: The requested team or invite does not exist
Team API token endpoints
------------------------
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/tokens/
Returns a list of all API tokens of a team.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/tokens/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"active": true,
"name": "Test token"
}
]
}
:query integer page: The page number in case of a multi-page result set, default is 1
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team does not exist
.. http:get:: /api/v1/organizers/(organizer)/teams/(team)/tokens/(id)/
Returns information on one token, identified by its ID.
**Example request**:
.. sourcecode:: http
GET /api/v1/organizers/bigevents/teams/1/tokens/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"active": true,
"name": "Test token"
}
:param organizer: The ``slug`` field of the organizer to fetch
:param team: The ``id`` field of the team to fetch
:param id: The ``id`` field of the token to fetch
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to view this resource.
:statuscode 404: The requested team or token does not exist
.. http:post:: /api/v1/organizers/(organizer)/teams/(team)/tokens/
Creates a new token.
**Example request**:
.. sourcecode:: http
POST /api/v1/organizers/bigevents/teams/1/tokens/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json
Content-Length: 94
{
"name": "New token"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json
{
"id": 2,
"name": "New token",
"active": true,
"token": "",
}
:param organizer: The ``slug`` field of the organizer to modify
:param team: The ``id`` field of the team to create a token for
:statuscode 204: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
:statuscode 404: The requested team does not exist
.. http:delete:: /api/v1/organizers/(organizer)/teams/(team)/tokens/(id)/
Disables a token.
**Example request**:
.. sourcecode:: http
DELETE /api/v1/organizers/bigevents/teams/1/tokens/1/ HTTP/1.1
Host: pretix.eu
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"id": 1,
"name": "My token",
"active": false
}
:param organizer: The ``slug`` field of the organizer to modify
:param team: The ``id`` field of the team to modify
:param id: The ``id`` field of the token to delete
:statuscode 200: no error
:statuscode 401: Authentication failure
:statuscode 403: The requested organizer does not exist **or** you have no permission to create this resource.
:statuscode 404: The requested team or token does not exist
Reference in New Issue View Git Blame Copy Permalink