Manage Organizations

This article describes how to register for an organization and how to manage the organization mapping of a Developer.
This article describes how to register for an organization and how to manage the organization mapping of a Developer.
As a Portal Admin, you can add, view, and can edit organizations in
API Management SaaS
. Organizations are a way to group and manage related Developers. API Owners can view the list of organizations. When you register a Developer, you assign the Developer to one or more organizations. Before you can register a Developer to a new organization, add the organization to
API Portal
.
You can also manage your organizations using the Portal API (PAPI) or use this API in your scripts for managing organizations.
Organization Registration
In
API Management SaaS
, you group registered application developers into organizations. Organizations contains one or more Developers. Commonly an organization includes Developers working together on one or more applications.
API Portal
assigns each Developer to a Developer user account or an Org Admin user account. Org Admin accounts provide more privileges than Developer accounts.
API Portal
assigns the first registered member of an organization to the Org Admin account.
API Portal
assigns Developers to user accounts in the following circumstances:
  • When the Developer registers their organization and themselves simultaneously,
    API Portal
    assigns the Developer to an Org Admin account.
    For example, if Sharon registers her organization, Lion Systems, and herself on
    API Portal
    , then
    API Portal
    assigns Sharon to an Org Admin account for Lion Systems.
  • The Org Admin sends a registration invitation to the developer. When the Developer accepts the invitation, the
    API Portal
    assigns the developer to a Developer user account and the Developer becomes a member of the organization.
    For example, Sharon can have the
    API Portal
    send Greg and Chloe invitations to register on the
    API Portal
    as members of her organization, Lion Systems. Sharon can specify that she wants
    API Portal
    to assign Greg to an Org Admin account and Chloe to a Developer account.
Register your Organization and Yourself
  1. From the menu bar, select the gear icon,
    Registration
    .
  2. Complete the Registration form. If you do not enter a name for your organization,
    API Portal
    assigns one.
  3. Select
    Register Now
    .
    (If single sign-on (SSO) is not enabled)
    API Portal
    sends you an account activation email.
  4. In the email message, select the account activation link.
    In
    API Portal
    , the Account Setup form opens.
  5. Complete the Account Setup form, and then select
    Activate Account
    .
Your organization is registered.
API Portal
assigns you to an Org Admin account.
Send a Registration Invitation to a Developer
Prerequisite:
Single sign-on (SSO) is not enabled.
  1. Log in to
    API Portal
    as an Org Admin.
  2. From the menu bar, select the gear icon,
    Registration
    .
  3. Select
    Invite User
    .
    The Invitation form opens.
  4. Complete the Invitation form, specifying which Developers get which account types, and then select
    Invite
    .
    API Portal
    sends the Developer invitations to register on
    API Portal
    by way of an email. When the Developer accepts the registration invitation, the Developer becomes a member of the organization.
Multi-Organization Mapping
You can map a user with a Developer account to multiple organizations, and specify what role this user will have within each organization.
If you are using multiple organizations, PAPI might not work properly because permissions are limited to only one organization at a time.
Which users can be mapped to multiple organizations?
  • Developers who are added and managed in
    API Portal
    .
  • Developers who log in to
    API Portal
    using an external authentication scheme, and the authorization type is set to "Portal".
    What is an
    authorization type
    ?
    Depending on how the user account exists,
    API Portal
    users can be categorized into two groups:
    • Portal:
      The user details and access levels can be edited and managed in
      API Portal
      .
    • Identity Provider:
      The user details cannot be edited and managed in
      API Portal
      . However, the user can be assigned to multiple organizations.
      For more information, see Map IdP Users to Multiple Organizations.
Who can map the Developers to multiple organizations?
  • Portal Admins
How can you map the Developers to multiple organizations?
  • While adding a Developer in
    API Portal
    .
  • (If the user is added and managed in
    API Portal
    ) While editing a Developer in
    API Portal
    .
  • (If the user logs in to
    API Portal
    using an external authentication scheme) Set the authorization type to "Portal", and edit the Developer details.
How do the organization names appear on the Users page?
Users who are assigned to
multiple
organizations are displayed in the
Users > Org Users
section, in the following format.
You can select
Multiple
to view and edit the organization and corresponding roles.
Add Organizations to
API Portal
Portal Admins can add organizations to
API Portal
using the
Add Organization
form. Every organization requires a name and account plan. You limit how much the applications developed by a Developer can use the API by way of an account plan. You can also use account plans to give some organizations access to private APIs.
For information about account plans, see Manage Account Plans.
Follow these steps:
  1. From the menu bar, select the gear icon,
    Organizations
    .
    The Organizations page appears.
  2. Select
    Add Organization
    .
  3. Enter a unique name for the organization (up to 255 characters).
  4. Select the organization type for the organization. By default,
    Consumer
    organization type is selected.
    • Publisher:
      Defines an organization that can have Org Publisher role users and allows managing APIs, publishing APIs, and proxy mappings. For example, a Publisher can be an internal organization that publishes an API and also consumes the API from API Portal.
    • Consumer:
      Defines an organization that can have users (Org Admin or Developer) who can only view and consume APIs. For example, a Consumer can be a partner organization that consumes an API from API Portal.
  5. Select an account plan for the organization, enter a public description of the organization, and then click
    Save
    .
View your List of Organizations
Portal Admins and API Owners can view a list of organizations on the
Organizations
page. The following information is displayed:
  • The name of the organization
  • The type of the organization
  • The account plan for the organization
  • The status of the organization
    • Enabled
      (Organization is active and contains developers)
    • Registration Init
      (Organization has been registered and is awaiting account setup completion)
    • Registration Pending Approval
      (Organization has been registered, account setup completed, and is awaiting approval)
Edit Organizations
Follow these steps:
  1. From the Organizations page, click on the organization name to edit organization details.
    The Edit Organization page appears.
  2. Edit the organization details. You can edit the organization name, organization type, the account plan, and the public description.
    Conversion of the Consumer organization type to a Publisher organization type does not require any conditions but for conversion of a Publisher organization type to a Consumer organization type, the organization must meet the following criteria. The organization should not:
    • have any Org Publisher role users
    • act as managing organization for any API
    • be part of the organization assignment list in any proxy
    Changing the
    Organization Type
    supersedes user permissions. For example, even if an API Developer has CRUD permissions for an API, the API Developer will be able to perform the CRUD operations only if the
    Organization Type
    of the user is
    Publisher.
  3. Click
    Save
    after making your changes.
Revoke Developer Access From an Organization
Org Admins can
only
revoke the access from Developers to their organizations. They cannot delete Developers from organizations.
Follow these steps:
  1. Log in to
    API Portal
    as an Org Admin.
  2. From the menu bar, select the gear icon,
    Users
    .
  3. In the
    Actions
    menu for the user, select
    Revoke Access
    .
  4. Select
    Ok
    .
Add Organization Tags
The Portal supports organization tagging to help Portal Admins group related organizations. Common grouping use cases include:
  • Internal organizations within a division
  • Hierarchy of organizations that consist of divisions and sub-divisions
  • Partner organizations from different regions
You may add and delete one or more tags for each individual organization OR bulk add and delete tags to multiple organizations at the same time.
Organization tags cannot be applied to APIs like API tags and vice versa.
Follow these steps:
  1. Log in to
    API Portal
    as an Org Admin.
  2. From the menu bar, select the gear icon,
    Organizations
    .
  3. On the Manage Organizations screen, select a check box for one or more of the organizations you would like to add tag(s) to. To select all the organizations in the list, click the bulk check box at the top of the list.
    The Actions box appears at the top of the screen.
  4. In the Actions box, enter one or more new tags or select from a list of existing tags to apply to your organization(s).
  5. Click
    Add Tag
    .
    Alternatively, if you want to remove the selected tag(s), click
    Delete Tag
    .
Performing a Filter Search by Organization Tags
To perform a filter search of organizations based on tags, click the Enter Tag drop-down list and select one or more existing tags. If you are searching by a single tag, the list displays organizations that have that tag. If you are searching by multiple tags, the list displays organizations with either the first tag, second tag, OR subsequent tags.
Managing Organization Tags with PAPI
You can also manage organization tags using the new
/tenant/-admin/1.0/tags
endpoint in the Portal API (PAPI).
Using the PATCH Operation
The operation:
PATCH /tenant-admin/1.0/tags/{tagUuid}/organizations
lets you bulk-update tag-organization associations by updating tags that you've listed in {tagUuid} AND simultaneously deleting the tags you did NOT list as part of the update. This operation allows you to quickly make sweeping tag-organization changes without having to perform a second removal step.
See the latest PAPI swagger file to learn more.
FAQs
Q: I am an Org Admin. Can I remove a user from
API Portal
?
No, you do not have the rights to remove a user from
API Portal
. Only Portal Admins can remove users. Org Admins can only revoke the user access from the organization.
Q: I am an Org Admin. Can I revoke access of any user?
You can only revoke access of a Developer who is,
  • added and managed in
    API Portal
    , and belongs to your organization
  • external IdP user with the authorization type changed to "Portal", and belongs to your organization.
Q: I mapped a user to an invalid organization in the external IdP. What happens now?
A user who does not have any access in
API Portal
or mapped to invalid organization or role while being authorized by IdP, becomes 'an
external user who does not belong to any organization
'. This user may be authenticated using external IdPs or using
API Portal
. In any case, they are listed in
Users
page with
Organization
and
Role
as 'None'.
To rectify:
  • If this user is managed by
    API Portal
    , you can edit the details to belong to one or more organizations.
  • If this user is authenticated using external IdPs, you can change the authorization type to 'Portal' and then edit the organization details.
    For more information, see Map IdP Users to Multiple Organizations.
Q: I revoked the user access from all their organizations. Now this user does not belong to any organization. Can this user still use
API Portal
?
The user can still log in to
API Portal
, but can only access the Home page and user profile page. The user is listed in the Users section with organization and role as 'None'. You can map this user to an organization and role, by selecting
Edit User
from the
Actions
menu.
Q:  I belong to two organizations, org1 and org2. I am currently logged in to
API Portal
for organization org1. How do I switch to the other organization? Do I need to log out?
No, you do not need to log out from
API Portal
. To use
API Portal
for your other organization, simply use the switch feature from My Profile, as shown in the following screenshot:
MultOrg.JPG