Table of contents
Enterprise Data Federation Service (EDFS)
Download API definition:
This API is a Technical Preview and is available for testing purposes only. Do not use in production.
POST https://api.bentley.com/edfs/itwins/{iTwinId}/packages/{uniqueName}/roles

Adds new integration package role to iTwin project role assignments for the integration package.

You can retrieve the available packageRoleIds

You can retrieve the available iTwinRoleIds for your iTwin project

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

User must be an Organization Administrator for the Organization that owns a given Project or have administration_manage_roles permission assigned at the Project level.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

User must also have the following permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given iTwin:

  • edfs_ilsmng to Manage Access to specific Integration Packages

Each integration package role has its own permission(s) assigned and the user who wants to manage them must have these permissions assigned as well.

Package roles and associated permissions

  • Execute Integration Package
    • edfs_objipexec to Execute Integration Package(s)

Request parameters

Name
Required?
Description
iTwinId
Yes

The iTwin project ID

uniqueName
Yes

The unique name of integration package

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with itwin-platform scope

Accept
Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

ITwinRoleToPackageRoleDtoList

Name
Type
Required?
Description
assignments
No

List of iTwin roles and their corresponding integration package roles

Example

json
{
    "assignments": [{
        "iTwinRoleId": "00000000-0000-0000-0000-000000000000",
        "packageRoleIds": [
            "00000000-0000-0000-0000-000000000000"
        ]
    }]
}

Response 200 OK

OK

json
{
    "assignments": [{
        "iTwinRoleName": "EDFS_integration",
        "iTwinRoleId": "00000000-0000-0000-0000-000000000000",
        "packageRoles": [{
            "packageRoleName": "Execute Integration Package",
            "packageRoleId": "00000000-0000-0000-0000-000000000000"
        }]
    }]
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json
{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 403 Forbidden

The user has insufficient permissions for the requested operation.

json
{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax)

json
{
    "error": {
        "code": "InvalidAssignmentListRequest",
        "message": "Cannot create AssignmentList.",
        "details": [{
                "code": "InvalidValue",
                "message": "Provided iTwin Role ID value is not valid.",
                "target": "ITwinRoleId"
            },
            {
                "code": "InvalidValue",
                "message": "Provided Package Role ID value is not valid.",
                "target": "PackageRoleIds"
            },
            {
                "code": "InvalidValue",
                "message": "Provided iTwin ID value is not valid.",
                "target": "iTwinId"
            },
            {
                "code": "InvalidValue",
                "message": "Provided Unique Name value contains invalid characters.",
                "target": "uniqueName"
            }
        ]
    }
}

Response 429 Too many requests

This response indicates that the user has sent too many requests in a given amount of time.

json
{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

Name
Description
retry-after

The number of requests exceeds the rate-limit for the client subscription.

ITwinRoleToPackageRoleDto

Name
Type
Description
iTwinRoleId
String

iTwin role ID

packageRoleIds
String[]

List of integration package role IDs

ITwinRoleToPackageRoleDtoList

Name
Type
Description
assignments

List of iTwin roles and their corresponding integration package roles

PackageRole

Name
Type
Description
packageRoleName
String

The name of the integration package role

packageRoleId
String

The ID of the integration package role

PackageRoleAssignmentDto

Name
Type
Description
iTwinRoleName
String

The name of the iTwin role

iTwinRoleId
String

The ID of the iTwin role

packageRoles

List of integration package roles assigned to the iTwin role

PackageRoleAssignmentDtoList

Name
Type
Description
assignments

List of iTwin roles and their corresponding integration package roles

DetailedError

Contains error information and an array of more specific errors.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

details

Optional array of more specific errors.

Detailed Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

Name
Type
Description
error

Error Detailed information.

Error

Contains error information.

Name
Type
Description
code
String

One of a server-defined set of error codes.

message
String

A human-readable representation of the error.

target
String, null

The target of the error.

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

Name
Type
Description
error

Error information.