--- title: Manage organizations description: Create, manage, and delete PingIDM organizations, owners, admins, members, and child organizations using the REST interface component: pingidm version: 8.1 page_id: pingidm:objects-guide:manage-orgs-rest canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/manage-orgs-rest.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Data Object Model", "Organizations"] section_ids: add-org-rest: Add an organization add-org-owner: Add an organization owner view-owner-orgs: List an owner's organizations add-org-member: Add an organization member list-org-members: List the members of an organization add-org-admin: Add an organization admin view-admin-orgs: List an admin's organizations add-org-member-as-admin: Add a member as an organization admin view-member-orgs: List a member's organizations add-child-org: Add a child organization view-owner-orgs-and-children: List an owner's organizations and child organizations --- # Manage organizations IDM provides RESTful access to managed organizations, at the context path `/openidm/managed/organization`. You can create, query, update, and delete managed organizations using the: * Platform admin UI Available at [icon: people, set=material, size=inline] Identities > Manage, and click the [icon: domain, set=material, size=inline] Organizations tab * Legacy admin UI (deprecated) Available at Manage > Organization * REST interface Available at `/openidm/managed/organization` The following examples show how to add, change, and delete organizations over the REST interface. For a reference of all managed organization endpoints and actions, refer to [Managed organizations](../rest-api-reference/endpoints/rest-managed-organizations.html). ## Add an organization Only IDM administrators can create top-level organizations. ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "name": "example-org" }' \ "http://localhost:8080/openidm/managed/organization/example-org" { "_id": "example-org", "_rev": "00000000bc9871c8", "adminIDs": [], "ownerIDs": [], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" } ``` ## Add an organization owner IDM administrators can create owners for an organization. This example makes `bjensen` the owner of the organization created previously. The example assumes that the managed user `bjensen` already exists: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request POST \ --data '{"_ref":"managed/user/bjensen"}' \ "http://localhost:8080/openidm/managed/organization/example-org/owners?_action=create" { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920", "_ref": "managed/user/bjensen", "_refResourceCollection": "managed/user", "_refResourceId": "bjensen", "_refProperties": { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920" } } ``` ## List an owner's organizations This example lists the organizations of which `bjensen` is an owner: ``` curl \ --header "X-OpenIDM-Username: openidm-admin" \ --header "X-OpenIDM-Password: openidm-admin" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/bjensen/ownerOfOrg?_queryFilter=true" { "result": [ { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920", "_ref": "managed/organization/example-org", "_refResourceCollection": "managed/organization", "_refResourceId": "example-org", "_refProperties": { "_id": "fcb0f4d0-dad2-4138-a80c-62407a8e831e", "_rev": "00000000496d9920" } } ], ... } ``` ## Add an organization member Organization owners can create members in the organizations that they own. In this example `bjensen` creates user `scarter` and makes him a member of the organization created previously: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "userName": "scarter", "sn": "Carter", "givenName": "Steven", "mail": "scarter@example.com", "password": "Th3Password", "memberOfOrg": [{"_ref": "managed/organization/example-org"}] }' \ "http://localhost:8080/openidm/managed/user/scarter" { "_id": "scarter", "_rev": "00000000eac81c23" } ``` ## List the members of an organization Organization owners can view the members of the organizations that they own. In this example, `bjensen` lists the members of example-org: ``` curl \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization/example-org/members?_queryFilter=true" { "result": [ { "_id": "b71e8dd9-6224-466f-9630-4358a69c69fd", "_rev": "0000000038ea999e", "_ref": "managed/user/scarter", "_refResourceCollection": "managed/user", "_refResourceId": "scarter", "_refProperties": { "_id": "b71e8dd9-6224-466f-9630-4358a69c69fd", "_rev": "0000000038ea999e" } } ], ... } ``` ## Add an organization admin Organization owners can create admins of the organizations that they own. An organization admin must be a member of the organization. In this example, `bjensen` makes `scarter` an admin of example-org: ``` curl \ --header 'Content-Type: application/json' \ --header "Accept-API-Version: resource=1.0" \ --header 'X-OpenIDM-Username: bjensen' \ --header 'X-OpenIDM-Password: Th3Password' \ --request PATCH \ --data '[ { "operation": "add", "field": "/admins/-", "value": { "_ref": "managed/user/scarter" } } ]' \ "http://localhost:8080/openidm/managed/organization/example-org" { "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" } ``` ## List an admin's organizations An organization owner or admin can only access the organizations that they own or administer. In this example, the admin `scarter` lists the organizations, and accesses only those of which they are an admin: ``` curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization?_queryFilter=true" { "result": [ { "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" } ], ... } ``` ## Add a member as an organization admin Organization admins can also add members to the organizations they administer. In this example, the organization admin, `scarter`, creates a new member, `jsanchez`, and makes them a member of example-org: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "userName": "jsanchez", "sn": "Sanchez", "givenName": "Juanita", "mail": "jsanchez@example.com", "password": "Th3Password", "memberOfOrg": [{"_ref": "managed/organization/example-org"}] }' \ "http://localhost:8080/openidm/managed/user/jsanchez" { "_id": "jsanchez", "_rev": "00000000f9341bd6" } ``` ## List a member's organizations Organization owners and admins can list the organizations of which a user is a member, as long as those organizations are owned or administrated by them. In this example, scarter lists the organizations of which jsanchez is a member: ``` curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/user/jsanchez?_fields=memberOfOrg" { "_id": "jsanchez", "_rev": "00000000f9341bd6", "memberOfOrg": [ { "_ref": "managed/organization/example-org", "_refResourceCollection": "managed/organization", "_refResourceId": "example-org", "_refProperties": { "_id": "078d14b2-e5f1-4b21-9801-041138e691f4", "_rev": "00000000ac2e9927" } } ] } ``` The organization established by the previous set of examples can be represented as follows: ![example-org](_images/example-org.png) In this organization, both `bjensen` and `scarter` can create and delete sub-organizations, also known as *child organizations*, of example-org, and can create and delete members within these child organizations. The following example shows how to add and delete child organizations over the REST interface: ## Add a child organization Organization owners and admins can create and manage child organizations of the organizations that they own or administer. In this example, the organization owner, `bjensen`, creates a new organization named `example-child-org`, and makes it a child organization of `example-org`: ``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "name": "example-child-org", "parent": {"_ref": "managed/organization/example-org"} }' \ "http://localhost:8080/openidm/managed/organization/example-child-org" { "_id": "example-child-org", "_rev": "00000000db852a9d" } ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The organization model is based on [delegated administration](../auth-guide/delegated-admin.html). As with delegated administration, you cannot explicitly change the relationship endpoints. So, for example, so you cannot create, update, delete, or patch relationship edges. The following type of request is therefore *not possible* with the organization model:``` curl \ --header "Content-Type: application/json" \ --header "X-OpenIDM-Username: bjensen" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --header "If-None-Match: *" \ --request PUT \ --data '{ "name": "example-child-org", "parent": {"_ref": "managed/organization/example-org"} }' \ "http://localhost:8080/openidm/managed/organization/children?_action=create" ``` | ## List an owner's organizations and child organizations Organization owners and admins have access to any organizations that are *child* organizations of their own orgs. In this example, admin scarter lists his visible organizations again: ``` curl \ --header "X-OpenIDM-Username: scarter" \ --header "X-OpenIDM-Password: Th3Password" \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "http://localhost:8080/openidm/managed/organization?_queryFilter=true" { "result": [ { "_id": "example-org", "_rev": "000000009c248a4a", "adminIDs": [ "scarter" ], "ownerIDs": [ "bjensen" ], "parentAdminIDs": [], "parentIDs": [], "parentOwnerIDs": [], "name": "example-org" }, { "_id": "example-child-org", "_rev": "00000000db852a9d", "adminIDs": [], "ownerIDs": [], "parentAdminIDs": [ "scarter" ], "parentIDs": [ "example-org" ], "parentOwnerIDs": [ "bjensen" ], "name": "example-child-org" } ], ... } ``` Notice that `scarter` can now access the example-child-org that `bjensen` created in the previous example.