Authorization Roles on the Platform
Information about the authorization roles needed for running the Akana API Platform API.
Note: the information in this article relates to authorization roles specifically for running the API platform API. For information about the authorization roles for platform users, within the Community Manager developer portal itself, see What are the default roles for the API platform? (Community Manager developer portal help).
This topic includes:
Overview
Some operations can be performed even if a user is not logged in to the platform, such as viewing certain types of content. Other operations, such as adding an app, require login.
In some cases, activities are further restricted so that certain operations can only be performed by a member of a certain user group or group. For details about these scenarios, see Access to Private Resources and Content below.
Certain roles, such as the Site Admin or Business Admin, have a senior level of access to multiple resources.
The default authorization roles used by the Akana API Platform API are listed and explained below.
In a case where the user sending an API request has insufficient authorization, there are two possible results:
- If an API call doesn't meet the necessary authorization role criteria—for example, the operation requires Business Admin permission and the user is not a Business Admin—it fails, with an HTTP 401 Unauthorized response.
- If a user doesn't have the required access to a private resource, the operation runs successfully, returning an HTTP code 200, but information relating to the private resource is not returned. Depending on the scenario, the response might include a subset of information or might not contain any information at all.
The documentation for each operation includes information on the authorization roles that are required to run the operation.
Notes:
- The authorization roles specified are platform defaults. Roles are configurable; a specific installation might include customization of roles.
- For a high-level summary of all roles, see What are the default roles for the API platform? (Community Manager developer portal help). The table below addresses roles specifically in the context of using the platform API.
Platform API Authorization Roles: Summary Table
| Role | Valid for these Resources | Description |
|---|---|---|
| Admin | API, AppVersion, Group |
The Admin role is general to any type of resource, such as an API Admin, app team member, or Group Administrator. You'll see this role designation in operations that apply to multiple resource types. Note: The role Admin applies to the app; the role AppAdmin applies to the APIContract. |
| APIAdmin | API, AppVersion, APIContract. |
An administrator for a specific API. For more information, see Details about API Admin rights. Note: API Administrator and API Admin are the same role. |
| API Owner | API | Responsible for adding an API. In a scenario where a basic platform user cannot add APIs, a user who is assigned the role of API Owner can add APIs. The user who creates the API becomes the first API Admin. |
| ApiInvitedUser | APIContract | Indicates whether the user is authorized for the resource the contract relates to. |
| AppAdmin (App Team Member) | APIContract |
A member of the app team for a specific app. Each app team member has full permission for operations relating to the app, including adding, modifying, and deleting apps and app versions as well as adding or removing other app team members. Details about app team member rights. All app team members have the same rights and capabilities; there is no distinction between an app admin and an app team member. Note: The role Admin applies to the app; the role AppAdmin applies to the APIContract. |
| Business Admin | Any, including the tenant | In a tenant scenario, a user who is a Business Admin for the tenant has full permission to all objects within the tenant business organization, including all apps and APIs. The Business Admin also manages some other resources, such as scopes and licenses. Details about Business Admin rights. |
| Developer | App | Used in relation to an app; a Developer is an app team member, and has the same access rights as an App Admin. |
| Federation Member | API, App, Group | In a federation scenario only: Any federation member, for the tenant hosting the applicable resource. |
| Follower | API, app, group, user-defined Board | For any resource that can be followed; indicates a follower of the resource. |
| InvitedUser | APIVersion | Indicates whether the user is an authorized user for the API version. |
| Leader (Group) | Group |
API Scope Groups and independent groups only: A user who has a Leader role in the group. For example, can promote or demote Group Members and other Group Leaders. Details about API Scope Group and Independent Group member and leader rights. |
| Login not required | Anyone | Indicates that an operation can be called by an anonymous user; signing up for the platform and logging in is not required. These operations have no authentication. For example, an anonymous user can view public APIs or site documentation. |
| Member (Group) | API | API Scope Groups and independent groups only: A user who has a Member role in the group. Details about API Scope Group and Independent Group member and leader rights. |
| Private Group Leader | APIVersion | A user who has been invited to the Leader role in an API Scope Group associated with an API version. Details about API Scope Group and Independent Group member and leader rights. |
| Self | User |
For sensitive activities relating to the user's own resources, such as changing the password, this role validates that the individual performing the activity is the resource owner. Most operations relating to users, such as changing user preferences and settings, can be performed only by the user (for himself/herself) or the Site Admin (for any user). Any operations that include {UserID} in the URL have an authorization role of Self. The UserID in the URL must match the UserID of the authenticated user, unless the API operation is being run by a Site Admin. |
| Site Admin | Any, including the tenant | The administrator of the tenant on which a resource exists. The Site Admin can see resources such as apps and APIs, but cannot modify them. The Site Admin also has access to additional parts of the user interface for configuration and monitoring purposes. Details about Site Admin rights. |
| System Administrator | Any, including the tenant |
The administrator of the tenant on which a resource exists, and also of the underlying infrastructure. The System Administrator has additional rights that the Site Admin does not have. For example, the System Administrator role is required for operations in the Index Administration Service for managing the Elasticsearch index. For information about assigning the System Administrator role, refer to Assigning a role to a user (Policy Manager help). |
| User (Registered User) | User |
A user who is logged in. Certain operations, such as changing the password, can be performed only by the authorized user (see self). Login is required for all operations relating to users except the operations relating to initial signup. Private resources are available to a user only if the user has been granted specific access to those resources. |
Access to Private Resources and Content
Some operations can be performed even if a user is not logged in to the platform, such as viewing certain types of content. However, when resources are marked as Private, a user doesn't see those resources even if an operation doesn't require login. For any resources or content with additional access restrictions applied to it, a user must meet additional requirements before seeing the resource or content. The operation will still run successfully, but the private results will not be returned.
For example, the GET /api/apis operation returns a list of all APIs on the platform. For a user invoking this operation, it returns a list of all public APIs and any additional APIs for which the user has access, providing the user is logged in. Private APIs to which the user doesn't have access do not appear on the list.
Another examples is the GET /content/get operation, which returns content. If the content being requested relates to a Private API and is marked as private, the content is not returned unless the user is authorized to have access to the content. In some cases a Private API might have some content designated as Private and some designated as Public. In this case, the public content is returned to all users, but the private content is not.
Private API Access
If an API version is private, it can be seen only by a user who has one of the following roles:
- API Administrator
- Business Administrator
- Site Administrator
- Invited users (includes API Scope Group members and members of additional groups invited by the Private API Administrator)
Private App Access
If an app version is private, it can be seen only by a user who has one of the following roles:
- App team member
- Business Admin
- Site Admin
Private Group Access
To view information relating to a group that's designated as Private, a user must have one of the following roles:
- Group Administrator (for an API Scope Group, the API Administrator)
- Group member
- Group leader
- Site Admin
- Business Admin