API Documentation v1

REST API Access Manager 2023.3.0.0 Manual for Developers

Glossary

Introduction

The Access Manager API allows external software products to control functions of Access Manager. The API is HTTP-based RESTful API which adhere the REST architectural constraints.

General

Paths

All paths in the API start with {Domain}/api/{version}. The current version of the API is v1.

An access to an API resource is thus for example via the URL http://{domain}/api/v1/resource.

Special characters in query parameters must be encoded if necessary. In some cases it may be necessary to replace a blank character by %20, a backslash \ by %5C and the forward slash / by %2F. For example, \\\\server\\name\\share name\\folder name becomes %5C%5Cserver%20name%5Cshare%20name%5Cfolder%20name.

Validation

All actions, that can be performed using the API, can also be performed via the AM web frontends. However, input data is validated less strictly by the API than it is by the web frontends. Meaning, a request that causes a validation error by the web frontend could still be valid for the API.

System generated IDs

Throughout the AM API, artificial IDs, generated by the system, are used to identify resources. A resource ID returned by the API will remain valid as long as the resource exists but may become invalid if certain aspects of the resource (e.g.its name) change. Also, it cannot be guaranteed that resource IDs remain compatible over several versions of AM.

Error messages

The error messages provided by the AM API are only informational.

HTTP Messages

The client and server talk to each other via messages. Clients send a request to the server, and the server replies with a response. Apart from the actual data, these messages also contain some metadata about the message. It is important to have some background knowledge about the HTTP 1.1 request and response formats.

HTTP Request

An HTTP request has the format which consists of:

<VERB> is one of the HTTP methods like GET, PUT, POST, DELETE etc.

<URI> is the URI of the resource on which the operation is going to be performed.

<HTTP Version> is the version of HTTP, generally HTTP v1.1.

<Request Header> contains the metadata as a collection of key-value pairs of headers and their values. These settings contain information about the message and its sender like client type, the formats the client supports, format type of the message body, cache settings for the response, and many more information.

<Request Body> is the actual message content. In this API, if the content has been provided in request body to any method of the service, it should always be in JSON format.

HTTP Response

An HTTP Response has the format which consists of:

The server returns <Response Code>, which contains the status of the request. This response code is generally the 3-digit HTTP status code.

Status codes indicate the result of the HTTP request.

<Response Header> contains the metadata and settings about the response message.

<Response Body> contains the representation of data if returned by the method.

Authentication

To access the API, the user must have been assigned the role API User. The user rights can be assigned or updated under Administrator / Settings / System Roles.

Authentication in AM API is always done against active directory users. A technical service account should be created in order to access the API. The available authentication methods depend on IIS configuration. The following methods have been tested to work:

• Windows Authentication (NTLM)
• Windows Authentication (Negotiate / Kerberos)
• Digest Authentication
• Basic Authentication

The used method depends on the client's capabilities and operating system. Basic Authentication guarantees maximum compatibility, but please make sure to use TLS / SSL secured connection because credentials are transmitted in clear text.

Token-based authentication using OAuth or OAuth2 mechanism is currently not supported.

Resources and Methods

The following chapters describe all resources provided by the Access Manager API and their applicable methods.

The following modules of Access Manager are relevant:

• Fileserver Management (API module string: FolderManagement)
• SharePoint Management (API module string: SharePoint)
• 3rd Party Management (API module string: ThirdParty)
• Profile Management (API module string: Profile)

Dependent on the module, some parameters can only have values as shown in the table below.

In addition to the possible error responses described in each of the following chapters, every API method can return the error response 400 Bad Request. This response indicates that the request was malformed and should not be repeated without modifications. Possible reasons for a 400 response include:

• The request body was not valid JSON
• A non-optional parameter was omitted
• A parameter had a value of the wrong type
• A parameter had an invalid value that cannot be made valid by changing the system status, e.g., the parameter module had a value other than FolderManagement, SharePoint, ThirdParty or Profile

Permissions

With the resource Permissions, access rights or permissions for supported locations can be managed. It can be accessed by the path /permissions.

The JSON representation of a permission object is defined below:

CreatePermissionModel:

{
  "module": "FolderManagement or SharePoint or ThirdParty or Profile",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User or Profile",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or UserProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership", // See permission set of location
  "valid_from": "YYYY-MM-DD", // optional date
  "valid_through": "YYYY-MM-DD" // optional date
}

PermissionResponseModel:

{
  "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ", // System generated permission id
  "module": "FolderManagement or SharePoint or ThirdParty or Profile",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User or Profile",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or UserProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership", // See permission set of location
  "valid_from": "YYYY-MM-DD", // optional date
  "valid_through": "YYYY-MM-DD" // optional date
}

Get Permissions by URL Parameters

GET /api/v1/permissions

Gets a list of permissions filtered by user_id or location.

This method only returns individual (direct) permissions or permissions via profiles on a location.
To get the effective permissions on a location, use Get Effective Permissions of a Location on the Locations resource.

Parameters

Detailed descriptions

subject_type: Can be User or Profile or both, separated by comma. If omitted, falls back to User.
If user_id is supplied, the combination of both User and Profile is not allowed.
When using User, user_id must be an active directory user or group name.
When using Profile, user_id must be a profile name.

Enumerated Values

Example responses

200 Response

[
  {
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "module": "FolderManagement",
    "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
    "subject_type": "User",
    "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or ProfileName",
    "permission": "read or write or design or owner or member or visitor or profilemembership",
    "valid_from": "2023-12-04",
    "valid_through": "2023-12-04",
    "comment": "string"
  }
]

Responses

Response Schema

Status Code 200

Enumerated Values

Add Permission

POST /api/v1/permissions

Adds new privileges to a user or a profile on a certain location.

The request body must be a JSON object containing the module, location, subject_type, user_id, the permission to grant, and optional start (valid_from) and expiration (valid_through) dates.

If the supplied location uses supplementary permissions, and the supplied user_id already has different permissions on the location, the supplied permission is added to the user’s permissions and the start (valid_from) and expiration (valid_through) dates are replaced on all of the user’s permissions on the location.

Body parameter

{
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or ProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string"
}

Parameters

Example responses

201 Response

{
  "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or ProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string"
}

Responses

Get Permission by PermissionId

GET /api/v1/permissions/{permissionId}

Gets the permission details of the provided permissionId.

Parameters

Example responses

200 Response

{
  "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or ProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string"
}

Responses

Remove Permission

DELETE /api/v1/permissions/{permissionId}

Removes the permission identified by permissionId.

Parameters

Detailed descriptions

permission: If the location uses supplementary permissions, the permission to be deleted can be identified using the optional query parameter permission.
If the permission parameter is omitted, all permissions of the user on the location are deleted.

Example responses

404 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Update Permission

PUT /api/v1/permissions/{permissionId}

Updates the access rights (permission) or also start (valid_from) and expiry (valid_through) dates of a user or a profile to access a particular location.

The permission must already exist in the system.
It cannot be used to create new permissions.
The request body must be a JSON object containing the permission to update and optional start (valid_from) and expiry (valid_through) dates.
The permissionId must be passed in the URL.
If the start (valid_from) or expiry (valid_through) date is null or not provided in the request, it will be removed from AM.

If the location uses supplementary permissions, the permission parameter must contain the value *.
Only valid_from and valid_through are updated on all permissions of the user on the location.

Body parameter

{
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string"
}

Parameters

Example responses

200 Response

{
  "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ProfileName",
  "subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected] or ProfileName",
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string"
}

Responses

Scheduler

With the resource Scheduler, jobs can be scheduled. It can be accessed by the path /scheduler.

Schedule Renew Access Settings

POST /api/v1/scheduler/triggers/renew_access_settings

Schedules a job that renews the access settings.

This method works differently depending on the value of field offset_minutes:

• If the value of offset_minutes is greater than 0, it schedules the renew access settings job after the input provided time (minutes).
• If the value of offset_minutes is not provided or is equal to 0, it schedules the renew access settings job immediately if it is not already scheduled.

The job being scheduled and the required format of path depend on the supplied module:

Body parameter

{
  "offset_minutes": 10,
  "data": {
    "module": "FolderManagement",
    "path": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName"
  }
}

Parameters

Example responses

409 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Locations

With the resource Locations, different kinds of information about locations like folders and sites can be requested. It can be accessed by the path /locations.

Each AM module supports different types of locations. The following types are supported:

Get Locations by URL Parameters

GET /api/v1/locations

Gets a possibly filtered list of all locations known to AM.

The list can optionally be filtered using a combination of query parameters. Omitted filters are not applied. The following query parameters are supported:

module: If set, only locations of the given module are returned. Required, if location is set.

onlyVisibleInSsp: If set to true, only locations that are visible in the AM Self Service Portal (SSP) are returned.
Setting this filter to false has the same effect as omitting it: all locations are returned regardless of their visibility in the SSP.
This filter is ignored if location is set.

location: Load only the given location. If set, module must also be specified and onlyVisibleInSsp is ignored.

A successful request will return a (possibly empty) unordered list of location objects.
Each location object contains a system generated location identifier (id), a module, a location (e.g., folder path or site URL), a type (e.g., RightsFolder or ManagedSite) and the fields requests_enabled and supplementary_permissions.

requests_enabled is only set for locations of type RightsFolder, ManagedFolderCollection, ManagedSite or ManagedSiteCollection.
On location object of other types, it will always be null.
requests_enabled indicates, whether permissions on this location can be requested using the SSP.
It has no impact on the request API resource.
As modules like ThirdParty and Profile are not explicitly supported, possibility of being requestable can be decided by their SSP visibility (see above): if a resource object is not visible in SSP, you may judge this as not requestable – even though it is possible via this API function.

supplementary_permissions indicates whether the locations logic to grant permissions is set to "Supplementary Permissions" or "Exclusive Permissions". false in this case means the locations logic to grant permissions is set to "Exclusive-Permissions" which is the default for all types. The only type that supports "Supplementary Permissions" is 3rd party item (ThirdPartyItem).

Parameters

Detailed descriptions

OnlyVisibleInSsp: If set to true, only locations that are visible in the AM Self Service Portal (SSP) are returned. Setting this filter to false has the same effect as omitting it: all locations are returned regardless of their visibility in the SSP. This filter is ignored if location is set.

Enumerated Values

Example responses

200 Response

[
  {
    "type": "ResourceGroup",
    "id": "Zm0tZl9pZC00Mg",
    "requests_enabled": true,
    "supplementary_permissions": true,
    "module": "FolderManagement",
    "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
  }
]

Responses

Response Schema

Enumerated Values

Add Location

POST /api/v1/locations

Adds a new location.

The required format of the request model varies based on the location type:

ResourceGroup: CreateResourceGroupModel

{
  "type": "ResourceGroup",
  "module": "FolderManagement",
  "location": "ResourceGroupName",
  "description": "string"
}

FolderCollection: CreateFolderCollectionModel

{
  "type": "FolderCollection",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder",
  "resource_group_id": "Zm0tcmdpZC0x",
  "display_name": "string",
  "enable_rights_management": true,
  "agent_group_name": "Default",
  "domain_mode": "MultiDomain",
  "organizational_unit": "OU=ou,DC=domain,DC=tld",
  "local_ad_group_naming_pattern": "lg_{0}_{1:00000000}_{2}",
  "global_ad_group_naming_pattern": "gg_{0}_{1:00000000}_{2}",
  "admin_group": "DOMAIN\\group.name",
  "browse_group": "DOMAIN\\group.name",
  "enable_access_groups": true,
  "enable_new_folder_requests_on_folder_collection": true,
  "deviation_strategy": "IdentifyAndCorrect",
  "always_take_ownership": false,
  "audit_ownership_changes": false,
  "enable_realtime_permissions": true
}

If any other location type is provided, the API will respond with a 400 Bad Request response.

Body parameter

{
  "type": "ResourceGroup",
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
}

Parameters

Example responses

201 Response

{
  "type": "ResourceGroup",
  "id": "Zm0tZl9pZC00Mg",
  "requests_enabled": true,
  "supplementary_permissions": true,
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
}

Responses

Response Schema

Enumerated Values

Get Information by LocationId

GET /api/v1/locations/{locationId}

Returns details of the location identified by the provided locationId.

This requires an HTTP GET query including the locationId is sent to /locations.

Parameters

Example responses

200 Response

{
  "type": "ResourceGroup",
  "id": "Zm0tZl9pZC00Mg",
  "requests_enabled": true,
  "supplementary_permissions": true,
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
}

Responses

Response Schema

Enumerated Values

Remove Location

DELETE /api/v1/locations/{locationId}

Removes the location identified by the provided locationId.

This requires an HTTP DELETE query including the locationId is sent to /locations.

Only locations of type ResourceGroup, ManagedFolderCollection and FolderCollection support deletion. If any other location type is provided, the API will respond with a 400 Bad Request response.

Body parameter

{
  "type": "ResourceGroup"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Update Location

PUT /api/v1/locations/{locationId}

Updates the properties of the particular location.

The location must already exist in the system.
It cannot be used to create a new location.

the JSON object is required to contain the type of the location to update and additional required properties in the request body. The locationId is required to be passed in the URL.
The type of the location cannot be changed.
If any property is null or not provided in the request,
it will be removed from AM.

The required format of the request model varies based on the location type:

ResourceGroup: UpdateResourceGroupModel

{
  "type": "ResourceGroup",
  "location": "ResourceGroupName",
  "description": "string"
}

FolderCollection or ManagedFolderCollection: UpdateFolderCollectionModel

{
  "type": "FolderCollection",
  "display_name": "string",
  "enable_rights_management": true,
  "agent_group_name": "Default",
  "domain_mode": "MultiDomain",
  "organizational_unit": "OU=ou,DC=domain,DC=tld",
  "local_ad_group_naming_pattern": "lg_{0}_{1:00000000}_{2}",
  "global_ad_group_naming_pattern": "gg_{0}_{1:00000000}_{2}",
  "admin_group": "DOMAIN\\group.name",
  "browse_group": "DOMAIN\\group.name",
  "enable_access_groups": true,
  "enable_new_folder_requests_on_folder_collection": true,
  "deviation_strategy": "IdentifyAndCorrect",
  "always_take_ownership": false,
  "audit_ownership_changes": false,
  "enable_realtime_permissions": true
}

If any other location type is provided, the API will respond with a 400 Bad Request response.

Body parameter

{
  "type": "ResourceGroup"
}

Parameters

Example responses

200 Response

{
  "type": "ResourceGroup",
  "id": "Zm0tZl9pZC00Mg",
  "requests_enabled": true,
  "supplementary_permissions": true,
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
}

Responses

Response Schema

Enumerated Values

Get Owners of a Location

GET /api/v1/locations/{locationId}/owners

Gets the owners of the location identified by the provided locationId.

This requires an HTTP GET query including the locationId is sent to /locations and the part /owners behind the id.

Only locations of type FolderCollection, ManagedFolderCollection, Folder, RightsFolder, SiteCollection, ManagedSiteCollection, Site, ManagedSite and ThirdPartyItem support owners. If the provided locationId belongs to a ResourceGroup, a ThirdPartyItemCollection, a UserProfile, a ManagedUserProfile, or an OrgProfile, the API will respond with a 400 Bad Request response.

Parameters

Example responses

200 Response

[
  {
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "location_id": "Zm0tZl9pZC00Mg",
    "user_id": "DOMAIN\\account.name"
  }
]

Responses

Response Schema

Status Code 200

Replace Owners of a Location

PUT /api/v1/locations/{locationId}/owners

Replaces the owners of the location identified by locationId with the provided list of owners.

Only locations of type FolderCollection, ManagedFolderCollection, Folder, RightsFolder, SiteCollection, ManagedSiteCollection, Site, ManagedSite and ThirdPartyItem support owners. If the provided locationId belongs to a ResourceGroup, a ThirdPartyItemCollection, a UserProfile, a ManagedUserProfile, or an OrgProfile, the API will respond with a 400 Bad Request response.

If the location is managed, i.e. it is a ManagedFolderCollection, RightsFolder, ManagedSiteCollection, ManagedSite, or ThirdPartyItem, the provided list of owners must contain at least one entry. Otherwise, the API will respond with a 409 Conflict response.

Body parameter

[
  {
    "user_id": "DOMAIN\\account.name"
  }
]

Parameters

Example responses

200 Response

[
  {
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "location_id": "Zm0tZl9pZC00Mg",
    "user_id": "DOMAIN\\account.name"
  }
]

Responses

Response Schema

Status Code 200

Get Responsibles of a Location

GET /api/v1/locations/{locationId}/responsibles

Gets the responsibles of the location identified by the provided locationId.

Only locations of type ManagedFolderCollection, RightsFolder, ManagedSiteCollection, ManagedSite, ThirdPartyItem, UserProfile, ManagedUserProfile and OrgProfile support responsibles. If the provided locationId belongs to a FolderCollection, a Folder, a SiteCollection or a Site, the API will respond with a 409 Conflict response. If it belongs to any other location type, the API will respond with a 400 Bad Request response.

Parameters

Example responses

200 Response

[
  {
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "location_id": "Zm0tZl9pZC00Mg",
    "user_id": "DOMAIN\\account.name"
  }
]

Responses

Response Schema

Status Code 200

Replace Responsible of a Location

PUT /api/v1/locations/{locationId}/responsibles

Replaces the responsible of the location identified by locationId with the provided list of responsibles.

Only locations of type ManagedFolderCollection, RightsFolder, ManagedSiteCollection, ManagedSite, ThirdPartyItem, UserProfile, ManagedUserProfile and OrgProfile support responsibles. If the provided locationId belongs to a FolderCollection, a Folder, a SiteCollection or a Site, the API will respond with a 409 Conflict response. If it belongs to any other location type, the API will respond with a 400 Bad Request response.

Unless the location is a UserProfile, ManagedUserProfile or OrgProfile, the provided list of responsibles must contain at least one entry. Otherwise, the API will respond with a 409 Conflict response.

If the location is a UserProfile and has a member synchronization group configured, the API will respond with a 409 Conflict response.

Body parameter

[
  {
    "user_id": "DOMAIN\\account.name"
  }
]

Parameters

Example responses

200 Response

[
  {
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "location_id": "Zm0tZl9pZC00Mg",
    "user_id": "DOMAIN\\account.name"
  }
]

Responses

If the provided list of responsibles is empty and the location is not a UserProfile, ManagedUserProfile or OrgProfile, the message "Managed locations must have at least one responsible." is returned.
If the location is a UserProfile and has a Member Synchronization Group configured, the message "User profiles with member synchronization groups configured do not support responsibles." is returned.|ErrorResponseModel|

Response Schema

Status Code 200

Get Effective Permissions of a Location

GET /api/v1/locations/{locationId}/effective-permissions

Gets the effective permissions on the location identified by the provided locationId.

Only locations of type ManagedFolderCollection, RightsFolder, ManagedSiteCollection, ManagedSite, ThirdPartyItem, UserProfile, ManagedUserProfile and OrgProfile support effective permissions.
If the provided locationId belongs to a FolderCollection, a Folder, a SiteCollection, or a Site, the API will respond with a 409 Conflict response.
If it belongs to any other location type, the API will respond with a 400 Bad Request response.

This method only returns effective permissions on the location.
To get direct permissions, use Get Permissions by URL Parameters.
Note that profiles only have direct members, so effective and direct permissions should be identical.

Parameters

Example responses

200 Response

[
  {
    "permission": "read or write or design or profilemembership",
    "valid_from": "2023-12-04",
    "valid_through": "2023-12-04",
    "origin": "string",
    "id": "Zm0tNDItYXUtRE9NQUlOXGFjY291bnQubmFtZQ",
    "location_id": "Zm0tZl9pZC00Mg",
    "user_id": "DOMAIN\\account.name"
  }
]

Responses

Response Schema

Status Code 200

Get Permission Set of a Location

GET /api/v1/locations/{locationId}/permission-set

Gets the permission set on the location identified by the provided locationId.

The permissions in this set are those that must be used when working with permissions on this location.
For example, when creating a permission assign request.

Only locations of type ManagedFolderCollection, RightsFolder, ManagedSiteCollection, ManagedSite, ThirdPartyItem, UserProfile, ManagedUserProfile and OrgProfile have a permission set.

Parameters

Example responses

200 Response

[
  {
    "permission": "read or write or design or profilemembership",
    "display_names": {
      "en": "Read",
      "de": "Lesen"
    },
    "default": true
  }
]

Responses

Response Schema

Status Code 200

Agent Groups

With the resource AgentGroups, information about agent groups can be requested. It can be accessed by the path /agent-groups.

Get Agent Groups

GET /api/v1/agent-groups

Returns a list of all agent groups known to AM.

Example responses

200 Response

[
  {
    "name": "string",
    "description": "string",
    "assigned_agents": [
      {
        "name": "string",
        "last_config_update": "2023-12-04",
        "status": "IsUnassigned"
      }
    ],
    "assigned_locations": [
      {
        "type": "ResourceGroup",
        "module": "FolderManagement",
        "location": "string",
        "id": "Zm0tZl9pZC00Mg",
        "requests_enabled": true,
        "supplementary_permissions": true
      }
    ]
  }
]

Responses

Response Schema

Status Code 200

Enumerated Values

Requests

With the resource Requests, different kinds of requests can be managed. All request types share the common path prefix /requests. The following sections describe the types of requests that can be managed via the AM API.

Each request type supports different types of locations. Invalid combinations of request types and location types will result in a 409 Conflict error response with the message "Location not found". The Permission Assignment request type also supports requests for membership in a user profile.

Add Location Creation Request

POST /api/v1/requests/location-creations

Adds a new request for a new managed location below a certain managed or unmanaged parent location.

The JSON representation of a new location request object is defined below:

RequestLocationRequestModel:

{
  "module": "FolderManagement or SharePoint",
  "location": "\\\\server\\share\\folder or http://host/path",
  "user_subject_type": "User", // Determines the type of user_id. Must always be User.
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname",
  "requestor_subject_type": "User", // Determines the type of requestor_id. Must always be User.
  "requestor_id": "DOMAIN\\account.name",
  "new_location_name": "subfolder or subsite",
  "site_template": "STS#0", // only required if module is SharePoint
  "permission": "read or write or design", // optional
  "comment": "string"
}

If the field permission is omitted, the user will not be permitted on the new location, but the location will still be created.

The field site_template is only required if module is SharePoint.
Available site templates can be requested from SharePoint, e.g. via the REST API like this:

URL: http://{sharepoint-server}/{site-collection}/{site}/_api/web/GetAvailableWebTemplates(lcid=1033,doincludecrosslanguage=true) Method GET Query Parameters: $select=Name, $filter=IsHidden eq false and IsRootWebOnly eq false Example: http://{sharepoint-server}/{site-collection}/{site}/_api/web/GetAvailableWebTemplates(lcid=1033,doincludecrosslanguage=true)?$select=Name&$filter=IsHidden eq false and IsRootWebOnly eq false

Body parameter

{
  "new_location_name": "subfolder or subsite",
  "site_template": "STS#0",
  "permission": "read or write or design",
  "comment": "string",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User",
  "requestor_id": "DOMAIN\\account.name"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Add Permission Assignment Request

POST /api/v1/requests/permission-assignments

Adds a new request for permission assignments on a location (e.g., a folder) and for membership assignment in a user profile.

These requests only work for locations that use the exclusive permission grant logic.
For those locations that use the supplementary permission grant logic,
the "Permission-Update-Request" must be used.

The JSON representation of a permission assignment request object is defined below:

RequestPermissionRequestModel:

{
  "module": "FolderManagement or SharePoint or ThirdParty or Profile",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User", // Determines the type of user_id. Must always be User.
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User", // Determines the type of requestor_id. Must always be User.
  "requestor_id": "DOMAIN\\account.name",
  "permission": "read or write or design or owner or member or visitor or profilemembership", // See permission set of location
  "valid_from": "YYYY-MM-DD", // optional date
  "valid_through": "YYYY-MM-DD", // optional date
  "comment": "string"
}

• module must be one of [FolderManagement, SharePoint, ThirdParty, Profile]
• location must be a location matching the module, or the name of a managed user profile if Profile is selected as module.
• user_subject_type determines the type of user_id. Must always be User.
• user_id must be the Active Directory user sAMAccountName or group name with NetBIOS domain name prefix or the Microsoft Entra user principal name of the user or group that should be granted the permission.
• requestor_subject_type determines the type of requestor_id. Must always be User.
• requestor_id must be the Active Directory user sAMAccountName with NetBIOS domain name prefix of the user requesting the permission for the aforementioned user or group.
• permission must be a valid permission from the permission set of the location (always use the english named value).
• valid_from is an optional start date. It is only processed if module is Profile. It must be a date before valid_through.
• valid_through is an optional expiration date. It must be a date in the future.
• comment is optional and can be any text.

Body parameter

{
  "permission": "read or write or design or owner or member or visitor or profilemembership",
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User",
  "requestor_id": "DOMAIN\\account.name"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Add Permission Removal Request

POST /api/v1/requests/permission-removals

Adds a new permission removal request for a user on a certain location.

These requests only work for locations that use the exclusive permission grant logic.
For those locations that use the supplementary permission grant logic, the "Permission-Update-Request" must be used.

The JSON representation of a permission removal request object is defined below:

RequestWithCommentRequestModel:

{
  "module": "FolderManagement or SharePoint or ThirdParty",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName",
  "user_subject_type": "User", // Determines the type of user_id. Must always be User.
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname",
  "requestor_subject_type": "User", // Determines the type of requestor_id. Must always be User.
  "requestor_id": "DOMAIN\\account.name",
  "comment": "string"
}

Body parameter

{
  "comment": "string",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User",
  "requestor_id": "DOMAIN\\account.name"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Add Permission Update Request

POST /api/v1/requests/permission-updates

Adds a new request for permission updates on a 3rd party item that uses the supplementary permission logic.

The JSON representation of a permission update request object is defined below:

RequestMultiPermissionRequestModel:

{
  "module": "ThirdParty",
  "location": "ItemCollectionName/ItemName",
  "user_subject_type": "User", // Determines the type of user_id. Must always be User.
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname",
  "requestor_subject_type": "User", // Determines the type of requestor_id. Must always be User.
  "requestor_id": "DOMAIN\\account.name",
  "permissions": [
    "permission01",
    "permission02"
  ], // See permission set of location
  "valid_through": "YYYY-MM-DD", // optional date
  "comment": "string"
}

• module must be ThirdParty.
• location must be 3rd party item location (ItemCollectionName/ItemName).
• user_subject_type determines the type of user_id. Must always be User.
• user_id must be the active directory user sAMAccountName or group name with NetBIOS domain name prefix of the user or group that should be granted the permission.
• requestor_subject_type determines the type of requestor_id. Must always be User.
• requestor_id must be the active directory user sAMAccountName with NetBIOS domain name prefix of the user requesting the permission for the aforementioned user or group.
• permissions must be an array of valid permission from the permission set of the location or can be an empty array to remove permissions.
• valid_through is an optional expiration date. It must be a date in the future.
• comment is optional and can be any text.

Body parameter

{
  "permissions": [
    "permission01",
    "permission02"
  ],
  "valid_from": "2023-12-04",
  "valid_through": "2023-12-04",
  "comment": "string",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User",
  "requestor_id": "DOMAIN\\account.name"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

Add Responsible Role Assignment Request

POST /api/v1/requests/responsible-role-assignments

Adds a new request for the responsible role for a user on a certain location.

The JSON representation of a responsible role assignment request object is defined below:

RequestWithCommentRequestModel:

{
  "module": "FolderManagement or SharePoint or ThirdParty",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName",
  "user_subject_type": "User", // Determines the type of user_id. Must always be User.
  "user_id": "DOMAIN\\account.name",
  "requestor_subject_type": "User", // Determines the type of requestor_id. Must always be User.
  "requestor_id": "DOMAIN\\account.name",
  "comment": "string"
}

Body parameter

{
  "comment": "string",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder or http://host/path or ItemCollectionName/ItemName or ManagedUserProfileName",
  "user_subject_type": "User",
  "user_id": "DOMAIN\\account.name or DOMAIN\\groupname or [email protected]",
  "requestor_subject_type": "User",
  "requestor_id": "DOMAIN\\account.name"
}

Parameters

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

ManagedLocations

Delete Managed Location

DELETE /api/v1/managed-locations/{locationId}

Removes the location identified by the provided locationId.

Only locations of type RightsFolder, ManagedSite, ManagedFolderCollection, ManagedSiteCollection and ThirdPartyItem support removal of permission management.
If the provided locationId is not managed, the API will respond with a 404 Not Found response.
If it belongs to any unsupported location type, the API will respond with a 400 Bad Request response.

mode must be one of RetainGroupRemoveMembers, RetainGroupKeepMembers, DeleteAccessManagerGroups or DeleteInTargetSystem, where DeleteAccessManagerGroups is only supported by RightsFolder, ManagedSite, ManagedFolderCollection and ManagedSiteCollection and RetainGroupRemoveMembers and DeleteInTargetSystem are only supported by ThirdPartyItem.
If the mode is not supported by the location type, the API will respond with a 400 Bad Request response.

Parameters

Enumerated Values

Example responses

400 Response

{
  "message": "The request is invalid.",
  "model_state": {
    "model_property": [
      "Error description."
    ]
  }
}

Responses

If the given location does not support deletion, the message "Provided location does not support this operation." is returned. If the provided locationId does not support the mode, the message "Provided location does not support this operation." is returned.|ErrorResponseModel| |404|Not Found|If the given location does not exist in AM or is an unmanaged location, the message "Provided location does not exist." is returned.|ErrorResponseModel|

Add Managed Location

POST /api/v1/managed-locations

Adds a new managed location.

The required format of the request model varies based on the location type:

OrgProfile: CreateProfileModel

{
  "type": "OrgProfile",
  "module": "Profile",
  "location": "ProfileName",
  "cluster_path": "/",
  "description": "Description",
  "self_service_description": "Self Service Description",
  "responsible_account_names": ["DOMAIN\\john.doe", "DOMAIN\\jane.doe"],
}

UserProfile: CreateUserProfileModel

{
  "type": "UserProfile",
  "module": "Profile",
  "location": "ProfileName",
  "cluster_path": "/",
  "description": "Description",
  "self_service_description": "Self Service Description",
  "responsible_account_names": ["DOMAIN\\john.doe", "DOMAIN\\jane.doe"],
  "member_sync_group_name": "DOMAIN\\group.name",
  "use_profile_permission_groups": false,
  "self_service_enabled": true
}

RightsFolder: CreateRightsFolderModel

{
  "type": "RightsFolder",
  "module": "FolderManagement",
  "location": "\\\\server\\share\\folder",
  "container_id": "Zm0tZl9pZC0x",
  "owner_account_names": ["DOMAIN\\john.doe", "DOMAIN\\jane.doe"],
  "responsible_account_names": ["DOMAIN\\john.doe", "DOMAIN\\jane.doe"],
  "self_service_enabled": true,
  "data_protection_classification_name": "topSecret",
  "inherit_rights": true
}

Body parameter

{
  "responsible_account_names": [
    "string"
  ],
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName",
  "type": "ResourceGroup"
}

Parameters

Example responses

201 Response

{
  "type": "ResourceGroup",
  "id": "Zm0tZl9pZC00Mg",
  "requests_enabled": true,
  "supplementary_permissions": true,
  "module": "FolderManagement",
  "location": "ResourceGroupName or \\\\server\\share\\folder or http://host/path or ItemCollectionName or ItemCollectionName/ItemName or ProfileName"
}

Responses

Response Schema

Enumerated Values