Incorrect API Endpoint Path in Organization Management Documentation

[Pratheesha97]

Issue Description:

The documentation for the Organization Management APIs [1] contains incorrect API endpoint URL in the sample payloads.

For instance, the documentation provides the following curl command for creating an organization:

curl --location 'https://localhost:9443/o/api/server/v1/organizations' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic YWRtaW46YWRtaW4=' \
-d '{
  "name": "ABC Builders",
  "description": "Building constructions",
  "attributes": [
    {
      "key": "Country",
      "value": "USA"
    }
  ]
}'

Executing this curl results in a 404 error due to the incorrect endpoint URL ('/o'). The response is as follows:

{
    "code": 404,
    "message": "Organization specific routing failed.",
    "description": "Unsupported organization specific routing endpoint."
}

[1] - https://is.docs.wso2.com/en/latest/apis/organization-apis/org-organization-mgt/

Describe the improvement:

The correct API endpoint URL should be as follows (omitting '/o') :

https://<hostname>:<port>/api/server/v1/organizations

Additional information:

Product version: IS 7.0.0

[AnuradhaSK]

As mentioned in the API overview https://is.docs.wso2.com/en/latest/apis/, WSO2 IS serves two type of APIs.

Management APIs - APIs that are consumed by an application as WSO2 Identity Server as the Identity Provider.
Organization APIs - APIs that are consumed by the B2B SaaS applications for organization-level operations.

Root organization level operations (tenant level) are managed via management APIs. If you are trying to create an organization under the root org you need to try the API under Management APIs -> Organization management API https://is.docs.wso2.com/en/latest/apis/organization-mgt-rest-api/

The https://is.docs.wso2.com/en/latest/apis/organization-apis/org-organization-mgt/ is about onboarding organization under another organization which is not the root.

One thing to be fixed in https://is.docs.wso2.com/en/latest/apis/organization-apis/org-organization-mgt:

• [ ] Organization APIs can't be invoked using basic auth. Always organization specific token is required as mentioned in https://is.docs.wso2.com/en/latest/apis/organization-apis/authentication/. Update the authorization header of the samples

[Pratheesha97]

Hi @AnuradhaSK,

Thank you for the explanation. Noticed that the documentation in [1] and [2] has been updated to include a description highlighting the difference between the two, which is very helpful.

It would be great if we could also address the issue where the authorization header in the sample organization APIs [2] containing Basic Auth.

Thanks again for the clarification!

[1] - https://is.docs.wso2.com/en/latest/apis/organization-mgt-rest-api/ [2] - https://is.docs.wso2.com/en/latest/apis/organization-apis/org-organization-mgt/

Regards, Samadhi