Authentication

Scopes

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:

Global scope

Includes all accessible areas of Podio.

User scope

Includes access to areas related to the authenticated user, such as chat messages through the Conversations API or personal tasks.

Org scope

Includes access to organizations. The user will specifiy which specific organizations will be made accessible.

Space scope

Includes access to spaces. The user will specifiy which specific spaces will be made accessible.

App scope

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.

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.

Read permissions

Involves requesting and viewing data in the specified scope.

Write permissions

Involves creating and mutating existing data in the specified scope.

Delete permissions

Involves removing data in the specified scope.

All permissions

Involves all of the above-mentioned, giving full access to the specified scope.

Requesting access

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:

&scope=space:read space:delete

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:

&scope=global:all

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.

Hooks

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.

Tasks

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.

Search

When using the Search API, responses are automatically limited to the scope of the client.