Organizations

Manage organizations on the API platform.

API Platform Version: 8.3

Table of Contents

  1. What is an organization?
  2. How do I see the Organizations List?
  3. How do I view my organization information?
  4. What functions are available to the Business Administrator for a specific organization on the platform?
  5. How do I add an organization?
  6. How do I add a child organization to my existing organization?
  7. How do I view child organizations?
  8. How do I edit an organization?
  9. How do I move an organization to another parent?
  10. How do I delete an organization?
  11. How do I get the unique ID for my organization?
Business APIs and Apps:
  1. How do I manage APIs for my organization?
  2. How do I manage apps for my organization?
Business Policies:
  1. How do I manage policies for my organization?
  2. How do I add a policy for my organization?
  3. How do I edit a policy for my organization?
  4. How do I delete a policy for my organization?
  5. How do I move a policy from one organization to another?
  6. How do I activate a policy that's in Draft state?
  7. How do I add a new version of a policy that's in Active state?
Business Processes and Scripts:
  1. How do I manage processes for my organization?
  2. How do I manage scripts for my organization?
Business Security:
  1. How do I manage security for my organization?
  2. How do I assign security roles to users for my organization?
  3. What are the default roles for the API platform?
  4. Related Topics

What is an organization?

When you sign into the developer portal, the user interface you see, and the apps and APIs you can add, are at the root, or tenant, level.

You can also add a business organization, which is essentially a child organization to the root organization.

Each business organization can have its own apps and APIs, managed by one or more Business Admins.

As a Business Admin, you can also create child organizations. If needed, you can create a hierarchy of business organizations, each with its own apps and APIs.

Back to top

How do I see the Organizations List?

In the Organizations List, you can add, edit, view, or delete information about all the organizations for which you are a Business Admin on the developer portal.

To access the Organizations List
  1. Log in to the Developer Portal as a Business Admin.
  2. In the top navigation bar, click the Organizations icon.
    Default Theme: Hermosa Theme:
    Organizations icon, Default Theme Organizations icon, Hermosa Theme
  3. The Organizations List is displayed.

On the Organizations List, every organization set up on the platform is displayed. The layout is flat, not hierarchical; the parent/child structure is not visually represented, but the display for each organization shows the parent. In the example below, both organizations are children of ACME Payments Corporation.

Organizations List

Back to top

How do I view my organization information?

You can see a summary of the information set up for your organization, on the Details page.

To view the summary page for your organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.

Back to top

What functions are available to the Business Administrator for a specific organization on the platform?

If you are a Business Admin for a specific business organization on the platform, the following functions are available to you on the Organizations menu (Organizations > choose organization).

Default Theme: Hermosa Theme:
Left menu, Organizations, Default Theme Left menu, Organizations, Hermosa Theme

Back to top

How do I add an organization?

A Business Admin can add an organization at the top level, at the List of Organizations. You can also create a hierarchy of organizations; an organization can have child organizations.

To add an organization at the top level
  1. Log in to the Developer Portal as a Business Admin.
  2. Do one of the following:
  3. On the Add Organization page, left pane, enter required values:
    • Organization Name: A short name to identify the organization.
    • Organization Description: A brief description to share information about the organization. Markdown is available on this field. For more information, see Using Markdown.
  4. If needed, in the right pane:
    • Optional: Upload an icon for the business.
    • Optional: If you want the new business to be the child of another business, enter the Parent Organization Name. Start typing; the platform locates the matching record, and you can then select it.
    • Specify the type of organization. This is an internal designation you can use to organize your businesses on the platform. If not specified, it defaults to Department.
  5. Click Save.

Back to top

How do I add a child organization to my existing organization?

When you've set up an organization at the top level, you can create child organizations that are secondary to it.

If needed, you can create multiple levels of child organization.

To add a child organization to your existing organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. From the menu on the left, choose Organizations. Any existing child organizations are displayed, in the same way as top-level organizations are displayed on the Organizations List.
  4. Click Add. The Add Organization page appears. The parent organization name is displayed in the title bar.
  5. Enter required values:
    • Organization Name: A short name to identify the organization.
    • Organization Description: A brief description to share information about the organization. Markdown is available on this field. For more information, see Using Markdown.
  6. If needed, click the Advanced Options button on the right and specify the type of organization.
  7. Click Save.

Back to top

How do I view child organizations?

You can view a list of child organizations set up for your specific organization.

To view a summary of child organizations for your organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left menu bar, click Organizations. A list of child organizations is displayed.

Back to top

How do I edit an organization?

You can modify information about any parent or child organization for which you're a Business Admin.

To edit an organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. Click Edit.
  4. If needed, edit required values:
    • Organization Name: A short name to identify the organization.
    • Organization Description: A brief description to share information about the organization. Markdown is available on this field. For more information, see Using Markdown.
  5. If needed, change the parent organization: On the right, in the Parent Organization Name field, type the ID of the new parent. To get the correct ID, see How do I get the unique ID for my organization? below.
  6. If needed, click the Advanced Options button on the right and specify, or change, the type of organization.
  7. Click Save.

Back to top

How do I move an organization to another parent?

You can move an organization up or down in the organization parent/child hierarchy. Essentially you do this by changing the parent organization.

To move an organization to another parent
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. Click Edit.
  4. On the right, in the Parent Organization Name field, start typing the name of the organization you want to move it to. After the first three characters, the platform displays a list of matching organizations for you to choose from.
  5. Click Save. The organization is moved to the new parent.

Back to top

How do I delete an organization?

You can delete any parent or child organization for which you're a Business Admin.

To delete an organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. Click Delete.
  4. At the confirmation message, click OK. The organization is deleted.

Back to top

How do I get the unique ID for my organization?

For some activities, you might need to know the unique ID for your organization. You can easily get this from the URL of your business organization's Details page.

In the developer portal, go to Organizations and click your organization to go to the Details page.

The URL will be something similar to the below:

http://www.acmepaymentscorp:7400/apcorptenant/#/organization/4a127775-a46f-424a-9503-2e3491680331.apcorptenant/details

In this example, 4a127775-a46f-424a-9503-2e3491680331.apcorptenant is the unique ID for the organization.

Back to top

Business APIs and Apps:

How do I manage APIs for my organization?

In the API platform, providing you have sufficient permissions, you can add and manage APIs at the root level.

  • In Default Theme, click the Plus menu and choose Add a New API, or click the My APIs icon to view the apps list.
  • In Hermosa Theme, click the Plus sign and choose Add API.

The platform also supports setting up a business organization. You can then add apps and APIs at the organization level. You have full rights to manage these APIs, including:

  • Adding an API
  • Viewing APIs
  • Modifying an API
  • Deleting an API

To perform activities relating to apps and APIs at the organization level, you must first log in, and then choose the organization. You can then view and manage resources that were set up at the organization level.

For detailed instructions about managing APIs in the context of a business organization, refer to Organization APIs.

Back to top

How do I manage apps for my organization?

In the API platform, providing you have sufficient permissions, you can add and manage apps at the root level.

  • In Default Theme, click the Plus menu and choose Add a New App, or click the My Apps icon to view the apps list.
  • In Hermosa Theme, click the Plus sign and choose Add App.

The platform also supports setting up a business organization. You can then add apps and APIs at the organization level. You have full rights to manage these apps, including:

  • Adding an app
  • Viewing apps
  • Modifying an app
  • Deleting an app

To perform activities relating to apps and APIs at the organization level, you must first log in, and then choose the organization. You can then view and manage resources that were set up at the organization level.

For detailed instructions about managing apps in the context of a business organization, refer to Organization Apps.

Back to top

Business Policies:

How do I manage policies for my organization?

The API platform allows you to manage the policies that are available for your business organization. You can:

All the policies available for your business organization are available for all child organizations also.

Back to top

How do I add a policy for my organization?

There are two steps to adding a policy:

  • Define the basic information about the policy, such as name, description, and policy type: see To add a policy below.
  • Configure the policy to define what it actually does: see To configure a policy below.
To add a policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Click Add.
  5. In the Add Policy page, specify:
    • Policy Name: A short, descriptive name for the policy. Used on the policy summary page.
    • Policy Category: Choose from the standard list of policy types. Supported policy categories are:
    • Policy Sub-Type: When you choose a policy type, the Policy Sub-Type drop-down list appears. Choose from the standard list of sub-type for the specified policy type.
    • Policy Description: A brief description of the policy. Include any key information relating to how the policy is used and what it does.
  6. Click Save. The policy is added to the list of policies for the organization.
To configure a policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy on the list and click the title to access the policy details.
  5. In the Policy Summary section at the bottom, click Modify. The configuration page for the specific policy is displayed.
  6. Modify values as needed. For information about configuring a specific policy type, refer to About Policies.
  7. When done, click Save. The Modify window closes, and the Policy Summary is updated with your changes.

Back to top

How do I edit a policy for my organization?

There are two things relating to a policy that you can edit:

To edit a policy definition
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to edit, and then click the title to view the Details page for the policy.
  5. In the top section of the page for the policy, click Edit.
  6. Edit values as needed. You can edit:
    • Policy Name
    • Policy Category
    • Policy Sub-Type
    • Policy Description.
  7. Click Save.
To edit the configuration of a policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to edit, and then click the title to view the Details page for the policy.
  5. In the bottom section of the page for the policy, click Edit. A separate window opens with the policy configuration.
  6. Edit the policy values. Specific fields vary according to the policy type. For information about configuring a specific policy type, refer to About Policies.
  7. Save changes.

Back to top

How do I view policies that are set up for my organization?

Policies might be set up in the developer portal or in the underlying infrastructure, Policy Manager. To view the policies currently in effect for your organization, follow the steps below.

To view policies for a specific organization
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. To view details for a specific policy, find the policy on the list, and then click the title to view the Details page for the policy.
  5. To view in greater detail, click the View button in the bottom section. The policy is displayed in a separate window. Here, you can:
    • Check syntax
    • Check schema

    When done, click Cancel to close the separate window.

Back to top

How do I delete a policy for my organization?

When you delete a policy, it isn't reversible; you can add the policy again, but you will have to re-create it from scratch. You'll lose any work that went into creating the policy. Be sure you want to delete it.

You can delete a policy in the developer portal or in the underlying infrastructure. To delete from the developer portal, follow the steps below.

To delete a policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to delete, and then click the title to view the Details page for the policy.
  5. Click Delete.
  6. At the confirmation message, click OK. The policy is deleted.

Back to top

How do I move a policy from one organization to another?

You can move a policy that's in Draft state between business organizations as long as you are a Business Administrator for both organizations.

Note: Once a policy is in Active state, you can't move it between organizations.

To move a draft policy from one business organization to another
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to move, and then click the title to view the Details page for the policy.
  5. Click Edit.
  6. On the right, in the Parent Organization Name field, start typing the name of the organization you want to move it to. After the first three characters, the platform displays a list of matching organizations for you to choose from.
  7. Click Save. The policy is moved.

Back to top

How do I activate a policy that's in Draft state?

You can activate a policy that's in Draft state, either in the developer portal or in the underlying infrastructure, Policy Manager. To activate a draft policy in the developer portal, follow the steps below.

To activate a draft policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to activate, and then click the title to view the Details page for the policy.
  5. At the top right, click the down arrow to view the Additional Items menu, and then click Activate Policy, as shown below.

    Activating a draft policy

  6. In the Perform Workflow Actions pop-up, enter a brief statement about your action in the Comments field, and click OK. The policy is activated.

Back to top

How do I add a new version of a policy?

You can only add a new version of a policy if the policy is in Active state. The new version that's created is in Draft state. Follow the steps below.

To start a new version of an active policy
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Policies. All policies associated with the organization are displayed.
  4. Find the policy that you want to start a new version for, and then click the title to view the Details page for the policy.

    Note: The State value for the policy must be Active.

  5. At the top right, click the down arrow to view the Additional Items menu, and then click Start New Version, as shown below.

    Starting a new version of an existing policy

  6. At the confirmation message, click OK. A new version of the policy is created, in Draft state.

Back to top

Business Processes and Scripts:

How do I manage processes for my organization?

In the API platform, you can add processes at the organization level. You have full rights to manage these processes, including:

  • Adding a process
  • Viewing processes
  • Modifying a process
  • Deleting a process

To perform activities relating to processes and scripts at the organization level, you must first log in, and then choose the organization. You can then view and manage resources that were set up at the organization level.

For detailed instructions about managing processes in the context of a business organization, refer to Organization Processes.

Back to top

How do I manage scripts for my organization?

In the API platform, you can add scripts at the organization level. You have full rights to manage these scripts, including:

  • Adding a script
  • Viewing scripts
  • Modifying a script
  • Deleting a script

To perform activities relating to processes and scripts at the organization level, you must first log in, and then choose the organization. You can then view and manage resources that were set up at the organization level.

For detailed instructions about managing scripts in the context of a business organization, refer to Organization Scripts.

Back to top

Business Security:

How do I manage security for my organization?

The API platform allows you to assign one or more specific roles to users.

All roles defined in the underlying Policy Manager infrastructure, either for the root organization or for the current business organization, are available to be assigned to users in your organization.

This accommodates many use cases and allows you to assign rights to create, view, modify, and delete resources in your organization, to a very fine level of granularity. You can control user access rights to a much more detailed level than the Developer, API Admin, Business Admin, and Site Admin roles supported in versions of the API platform prior to version 8.3.

You can assign access roles to specific users in your organization via the Security page. See How do I assign security roles to users for my organization? below.

You can also add roles. Currently, new roles must be added in Policy Manager, and are then available for selection in the API Platform UI. Roles added at the root organization level are available for all organizations; you can also add one or more roles for a specific organization, and they are available only for that organization.

For information on adding roles in Policy Manager, refer to the Policy Manager help.

Back to top

How do I assign security roles to users for my organization?

You can assign access roles to specific users in your organization, via the organization's Security page.

To assign security roles to users
  1. In the Developer Portal, go to the Organizations List (see To access the Organizations List).
  2. Find your organization on the list, and then click the title to view the Details page for the organization.
  3. On the left navigation bar, choose Security. In the right pane, the Role Memberships page, all roles currently available to the organization are displayed. An example is shown below.

    Security role memberships

  4. On the list, find the role you want to assign, and click the Edit (pencil) icon to the right. The {role name} - Users page has two panes:
    • Left pane has a search bar to help you identify one or more users you want to assign the role to.
    • Right pane lists users currently assigned to the role.
  5. In the left pane, enter search criteria at the top, and then click Go, to locate users.
  6. To assign the user to the role, click Assign.
  7. When done, click Save.

Back to top

What are the default roles for the API platform?

In the developer portal, you can manage roles for the platform users who are part of your business organization, as explained in How do I assign security roles to users for my organization? above.

The summary below gives you the basic definition for each of the default roles. Note that your platform implementation might already include some customization of roles, in the underlying infrastructure. The definitions below are the defaults.

Default roles:
2FA-exempt users
A user who is exempt from platform 2FA verification. Even if two-factor authentication is required for platform users, it is not required for users with this role assigned.
API Administrator
Responsible for managing the API. The API Admin has full permission for operations relating to the API, including adding, modifying, and deleting APIs, API versions, and API implementations.
Note: A user assigned the API Administrator role in the context of a business organization, who is not invited to a specific API, does not have permission to manage API Admins, such as adding or removing other API Admins. Only a user invited to a specific API has those permissions. For details, see What API management capabilities are available to the API Admin in the platform?
API Developer
API Developers have read-only access to the API.
API Owner
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.
API Platform Users
Users who have signed up for the developer portal by creating an account, or have been added by a Site Admin and have then activated the account.
App Team Member
Responsible for managing an 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.
Business Administrator
Responsible for managing all aspects of a business set up on the API Platform. For details, see What functions are available to the Business Administrator on the platform?
Developer
Responsible for registering and building web services. This role is used by the underlying infrastructure, not by the developer portal. Do not assign or change this role in the developer portal.
Federation Member
A member of a tenant federation, in a scenario where federation is in effect for the platform implementation.
Group Administrator
Has full administrator rights for the specific group; for example, can add, remove, promote, or demote any group member, and can delete the group.
Group Leader
Has Group Leader rights; for example, can promote or demote Group Members and other Group Leaders.
Group Member
Has Group Member rights; for example, can invite others to join the group.
Guest
An anonymous user who is using the developer portal without logging in. Guests have view-only access to public content. If an API is set to allow anonymous access (depends on API implementation settings), the anonymous user can test the API in Test Client.
Infrastructure Manager
Responsible for installing containers, virtualizing services, and deploying services to containers. This role is used by the underlying infrastructure, not by the developer portal. Do not assign or change this role in the developer portal.
Operation Manager
Responsible for developing security and monitoring policies and assigning them to services and organizations.
Organization Administrator
Responsible for adding, modifying, and deleting organizations, and for managing services, policies, and containers within an organization.
Policy Administrator
Responsible for adding, modifying and deleting policies within an organization.
Provision Manager
Responsible for approving app/API contracts in any scenario where approval is required (depends on API implementation settings).
Security Administrator
Responsible for granting access to the Workbench for an organization, to users and user groups. This role is used by the underlying infrastructure, not by the developer portal. Do not assign or change this role in the developer portal.
Site Administrator
Responsible for managing many site administration tasks for the developer portal, such as configuration settings, the Site Admin team, and the platform developer agreement. For details, see What functions are available to the Site Administrator in the platform?
Tenant Business Administrator
Responsible for managing the APIs within the entire tenant installation.
Tenant Manager
Has full rights and permissions to manage the tenant installation.

Back to top