Podio uses the concept of scopes to manage access restriction in order to ensure a safe relationship between a user's account and the externally connected application.
Currently, five different scope types are defined:
Includes all accessible areas of Podio.
Includes access to areas related to the authenticated user, such as chat messages through the Conversations API or personal tasks.
Includes access to organizations. The user will specifiy which specific organizations will be made accessible.
Includes access to spaces. The user will specifiy which specific spaces will be made accessible.
Includes access to apps. The user will specifiy which specific apps will be made accessible.
The scope hierarchy
The scopes are defined in a form of hierachy, meaning that granting permissions to one scope will result in implicitly granting those same permissions to scopes lower in the hierarchy.
The following figure illustrates how permissions propagate through the different levels in the hierachy:
For example, giving access to the Space scope will also mean giving access to the App scope with identical permissions.
Apart from telling Podio which scopes it requires access to, the external application will also need to specify the extent to which it may handle data. We refer to this as specifiying scope permissions. Currently, there are four types of permissions.
Involves requesting and viewing data in the specified scope.
Involves creating and mutating existing data in the specified scope.
Involves removing data in the specified scope.
Involves all of the above-mentioned, giving full access to the specified scope.
Full details on the authentication flow and authentication URL are described in the following chapters, so this will simply highlight the areas related to scopes and permissions
The scope parameter
The required scope, as well as the specific scope permissions, are specified in the query parameter scope in the following format:
&scope=[scope]:[permission1] [scope]:[permission2] [scope]:[permissionN]
E.g. the following scope parameter requests read and delete permissions in the Space scope:
Note that omitting to specify the scope parameter or giving it an empty value is equivalent to requesting access to the Global scope with all permissions or:
As shown in the illustration above, the User scope is decoupled from the other scopes. This means that it can be requested in conjunction with either one of them. This is done by separating the scopes by a space character:
&scope=user:read user:delete space:all
Granted scope string
When the user has chosen the specific orgs, spaces or apps that they wish to grant access to (and confirmed), this information is made available in the returned scope parameter (for client-side flow) or an object property in the response in the access_token request (server-side flow)
The format of this string is similar to that of the scope parameter, but is different in that it includes the IDs of the specific references that the user has chosen. It conforms to the following format:
[scope1]_[id]:[permission1] [scope1]_[id]:[permission2] [scope2]_[id]:[permission1]
For example read and write permissions for user with ID 2050398 as well as delete permissions for app with ID 14956 would look like this:
user_2050398:read user_2050398:write app_14956:delete
Once authenticated, you can always get the current scope via the Get scope-endpoint.
Details by Area
The sections below provide some detail on how the respective areas interact with permissions.
A client only needs read permission on an app or space to have permission to create a web hook. The client used to create a web hook is automatically granted all permissions on the web hook.
The permissions a client has on a task is the union of the permissions the client has on the referred object (if any), the creator and the responsible. If a user has granted read user scope to a client, then the client thus has read permissions on all tasks created by or assigned to that particular user.
When using the Search API, responses are automatically limited to the scope of the client.