Organization REST API

The Organization endpoint allows managing your organization's structure.

In ActivID Appliance, an organization resource represents a Security Domain A specific data instance in the ActivID Appliance database. It provides a complete segregation of data for different business units within a single deployment..

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.

See also the Create an Organization Adapter tutorial.

Note: The API version supported by ActivID Appliance 8.7 is 3.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.

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"
      ]
   }
}

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"
    "startIndex": 0,
    "count": 100
}

Where:

Other filter names can be used to search organizations by their parameters.

You can use the and operator within the filters.
The following attributes can be used for a paginated search:
- count can be used to limit the size of the search results
- startIndex specifies the index of the first result returned (where 0 will returned the same paginated result as 1)
The result will contain a totalResults attribute to allow you to compute the number of pages.

Note:
The maximum number of rows returned per request is 100, even if you specify a higher count value. Therefore, for lists that are longer than 100 elements, it is mandatory for you to paginate the results.

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