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 developer portal itself, see What are the default roles for the API platform? (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? (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.
API Owner API The owner of a specific API. Defined in the underlying infrastructure. An API Admin can edit or delete any API for which he/she is an Admin; an API Owner can edit or delete an API only if he/she created the API.
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.

Back to top

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

Back to top

Related Topics