Organization REST API

The Organization endpoint allows managing your organization's structure.

In the federation use case, one tenant (federating) can perform operations defined by the scope of permissions in the other tenant (federated). The federating tenant uses the organizationDelegation attributes of the SCIM API when creating a federated tenant.

Note: The API version supported by HID Authentication Service is 10.2.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method	Entity Action	Request URI	Description
GET	Read	/scim/{tenant}/v2/Organization/	Get all organizations filtered by attributes
GET	Read	/scim/{tenant}/v2/Organization/{id}:(String)	Retrieve an organization
POST	Create	/scim/{tenant}/v2/Organization/	Create new organization
POST	Search	/scim/{tenant}/v2/Organization/.search	Search for organization
PUT	Replace	/scim/{tenant}/v2/Organization/{id}:(String)	Fully replace a known organization
DELETE	Delete	/scim/{tenant}/v2/Organization/{id}:(String)	Delete a known organization

Required Permissions

Function	Required Permissions
GET	Read organization
CREATE	Create organization
REPLACE	Update organization
DELETE	Delete organization
SEARCH	Search organization

Create an Organization

[POST] /Organization

Accept: application/scim+json

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Organization

Copy

Sample Request

{
    "id": "MY_ORG",
    "externalId": "MY_ORGANIZATION_EXTERNALID",
    "type": "TEMENOS",
    "initialPassword": "myInitialPassword",
    "publicAttributes": [{
            "name": "param1",
            "type": "string",
            "value": "value1",
            "readOnly": false
        }, {
            "name": "param2",
            "type": "string",
            "value": "value2",
            "readOnly": false
        }
    ],
    "organizationDelegation": {
        "schemas": ["urn:hid:scim:api:idp:2.0:OrganizationDelegation"],
        "idProof": "dGhpc0lzQVJhbmRvbVNlbnRlbmNl",
        "id": "id",
        "delegatedRoles": [
            "RL_1",
            "RL_2"
        ]
    },
    "organizationBranding": {
        "hidApproveCustoFiles": [{
                "filename": "myCustoFile0.json",
                "fileAsBase64": "<myCustoFile0 b64>"
            }, {
                "filename": "myCustoFile1.json",
                "fileAsBase64": "<myCustoFile1 b64>"
            }
        ],
        "authPortalCustoFile": {
            "filename": "myCustoFile.json",
            "fileAsBase64": "<myCustoFile b64>"
        }
    }
}

Copy

Sample Response

HTTP 200 OK
 
{
   "schemas": ["urn:hid:scim:api:idp:2.0:Organization"],
   "id": "MY_ORG",
   "externalId": "MY_ORGANIZATION_EXTERNALID",
   "meta":    {
      "resourceType": "Organization",
      "location": "https://[base-server-url]/scim/tenant/v2/Organization/MY_ORG",
      "version": "1"
   },
   "type": "TEMENOS",
   "initialPassword": "myInitialPassword",
   "publicAttributes":    [
            {
         "name": "param1",
         "type": "string",
         "value": "value1",
         "readOnly": false
      },
            {
         "name": "param2",
         "type": "string",
         "value": "value2",
         "readOnly": false
      }
   ],
   "organizationDelegation":    {
      "schemas": ["urn:hid:scim:api:idp:2.0:OrganizationDelegation"],
      "id": "id",
      "idProof": "dGhpc0lzQVJhbmRvbVNlbnRlbmNl",
      "delegatedRoles":       [
         "RL_1",
         "RL_2"
      ]
   },
   "organizationBranding":    {
      "hidApproveCustoFiles":       [
                  {
            "filename": "myCustoFile0.json"
         },
                  {
            "filename": "myCustoFile1.json"
         }
      ],
      "authPortalCustoFile":       {
         "filename": "myCustoFile.json"
      }
   }
}

Get an Organization

[GET] /Organization/{id}

Copy

Sample Request URI

[GET] /scim/{tenant}/v2/Organization/MY_ORG

Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:Organization"],
   "id": "MY_ORG",
   "externalId": "MY_ORGANIZATION_EXTERNALID",
   "publicAttributes":    [
            {
         "name": "param1",
         "type": "string",
         "value": "value1",
         "readOnly": false
      },
            {
         "name": "param2",
         "type": "string",
         "value": "value2",
         "readOnly": false
      }
   ],
   "organizationDelegation":    {
      "schemas": ["urn:hid:scim:api:idp:2.0:OrganizationDelegation"],
      "id": "DELEG_ORGANIZATION_ID",
      "externalId": "DELEG-ORG-EXTERNALID",
      "idProof": "dGhpc0lzQVJhbmRvbVNlbnRlbmNl",
      "delegatedRoles":       [
         "RL_1",
         "RL_2"
      ]
   }
}

Note: The startIndex and count parameters are not supported for GET/all requests.

Replace an Organization

The implementation is the same as for Create an Organization:

externalId is required.
An organizationDelegation can be specified.
An organizationBranding can be specified.

Also, the uid in the URL must match the id in the request body.

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.

Copy

PUT /scim/{tenant}/v2/Organization/{uid}
 
{
   "schemas": ["urn:hid:scim:api:idp:2.0:Organization"],
   "id": "{uid}",
 
...
 
}

Search for an Organization

Supported search criteria are:

SCIM Attribute	Operators supported
type	eq
externalid	eq
id	eq

Copy

Sample Request URI

[POST] /scim/{tenant}/v2/Organization/.search

Copy

Sample Request

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "filter": "type eq mytype and id eq myid and externalid eq myexternalid and MYPARAM eq MYVALUE and MYPARAM1 eq MYVALUE1"
}

Where:

Other filter names can be used to search organizations by their parameters.
You can use the and operator within the filters.

Note: The startIndex and count parameters are not supported for .search requests.

For further information, see Searching with the SCIM API.

Copy

Sample Response

{
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults": 2,
     "resources": [
         {
             "schemas": ["urn:hid:scim:api:idp:2.0:Organization"],
             "id": "1111",
             "externalId": "MYORG"
         },
        {
            "schemas": ["urn:hid:scim:api:idp:2.0:Organization"],
            "id": "2222",
            "externalId": "MYORG"
        }
    ]
}

Note:

If you are using the provided organization adapter sample, search organization will always return the sample response above.
If you enable DEBUG server logs and if you are using the provided organization adapter sample, filters value are logged in the following order:
- externalid
- id
- type
- param name - param value

For example, the sample request above will log:

Copy

2017-10-23 14:06:12,084 [default task-6] DEBUG (OrganizationAdapterSample.java:89) - search organization
2017-10-23 14:06:12,084 [default task-6] DEBUG (OrganizationAdapterSample.java:91) - myexternalid
2017-10-23 14:06:12,085 [default task-6] DEBUG (OrganizationAdapterSample.java:92) - myid
2017-10-23 14:06:12,085 [default task-6] DEBUG (OrganizationAdapterSample.java:93) - mytype
2017-10-23 14:06:12,085 [default task-6] DEBUG (OrganizationAdapterSample.java:100) - MYPARAM - MYVALUE
2017-10-23 14:06:12,086 [default task-6] DEBUG (OrganizationAdapterSample.java:100) - MYPARAM1 - MYVALUE1

For further information, see Searching with the SCIM API.

Delete an Organization

All the delete endpoints follow the same standard pattern and can be reached through the following URL pattern:

Copy

Delete entity

DELETE https://[base-server-url]/scim/{tenant}/v2/ENTITY_TYPE/{id}

Accept: application/scim+json

Copy

Sample Response

HTTP/1.1 204 No content