Permissions
Companies
Every time a user requests a token, they select which one of their companies the token has access to. Once a token has been created, there is no way to change the company it is linked to. If the user wants to access another company, they have to request another token.
While this sounds like a limitation, it also has a big benefit. Various endpoints work within the
context of a single company. For example, when creating a new event, it must belong to a company.
When the token only has access to one company, the system will just use that company. However, if
the token has access to multiple companies, the request must explicitly specify which company the
event belongs to. While this is possible, through the Company header, it makes the system more
cumbersome to use.
Therefore, each OAuth client is initially limited to single-company tokens. If your use case would benefit from the use of multi-company tokens, please contact apiteam@openticket.tech so we can configure your OAuth client accordingly and give you the complete explanation of how this mechanism works.
Roles
Each token has the same roles on the company as the user it belongs to. In other words, it is not possible to create a token with read-only access when the user has full access. Once the usage of scopes is enabled in the future, this restriction will effectively disappear.
When the user gains (or loses) roles, the roles of the token will update automatically and almost instantly. If a user loses all roles on a company, so do their tokens. Technically speaking, these tokens are still valid, but without any roles, they cannot actually be used. However, if the user gains roles again (for example, because their roles were removed by mistake), their tokens become usable again.
User for application
Many applications only perform operations when a user is actively interacting with them. In these cases, any user account can log in to such an application and use it. There are also applications which need to perform tasks in the background, when no user is interacting with them (for example, to periodically sync data). This can be accomplished by a user logging in once and the application then using refresh tokens to keep the user logged in indefinitely. This process is commonly called "connecting the application". In this case, which user account to use for the connection can make a big difference.
We noticed that whichever employee makes the connection will often simply use their own account. At first glance this works well enough, but it does have some disadvantages. For example, if that user ever leaves the company, the connection to your application breaks, possibly without warning. If the user is reduced from full access to read-only access, so is your application. Likewise, if the user gains full access, so does your application. (If the organiser does not want to give your application full access, they cannot promote their user.)
For the reasons above, we recommend organisers make a special user for each connection. This way, the access rights of your application can be set using the access rights of that user. Should the organiser want to break the connection, they have an easy way to do so. But when they do not want to break the connection, there is no risk of this happening accidentally.
Note that which user account to use for a connection is ultimately the choice of whoever creates the connection. While you can make the suggestion above in documentation and when talking to your customers, the system has no way to enforce it. This is partly because such a constraint cannot be checked automatically, but also because, while it is good advice, disallowing it outright is too restrictive.