Public sharing

Public sharing allows a resource to be shared with consumers who don't otherwise have access to the resource, for example because they are not registered on the HxDR platform. For this example, we will look at grouped assets. Sharing other resources works the same way.

Resources are shared using a sharing code. This code can be generated by a user who has access to the resource, and had the CAN_PUBLIC_SHARE project capability. Revoking a sharing code has the same requirements.

Creating a sharing code

A sharing code can be created on a grouped asset using the following mutation

mutation {
  shareGroupedAsset(groupedAssetId: "a8390ba8-23af-48fa-97dd-79abd944fa2f") {
    __typename
    ... on SharingCodeOutput {
      sharingCodeId
    }
    ... on BaseAcsErrorInterface {
      message
    }
  }
}

The reply will contain the sharing code:

{
  "data": {
    "shareGroupedAsset": {
      "__typename": "SharingCodeOutput",
      "sharingCodeId": "c6dab346-f791-4658-a58b-fe132c0f4382"
    }
  }
}

This sharing code can now be shared publicly. This can for example be done in a URL parameter.

Using a sharing code

When a user tries to access a publicly shared asset, the client must first convert the sharing code into an authorization signature. The following query does not require the authorization header:

query {
  sharedGroupedAsset(sharingCodeId: "c6dab346-f791-4658-a58b-fe132c0f4382") {
    __typename
    ... on SharedGroupedAssetOutput {
      id
      auth
    }
    ... on BaseAcsErrorInterface {
      message
    }
  }
}

The response will contain the shared grouped asset ID in the id field, as well as the authorization signature in auth.

{
  "data": {
    "sharedGroupedAsset": {
      "__typename": "SharedGroupedAssetOutput",
      "id": "a8390ba8-23af-48fa-97dd-79abd944fa2f",
      "auth": "ff8iyYJWRDfen_BbTTW8YR3[...]akfs5OI"
    }
  }
}

With this information, the grouped asset can be retrieved. The string returned in auth should be prefixed with Signature (must start with capital S), and put in the Authorization header:

{
  "Authorization": "Signature ff8iyYJWRDfen_BbTTW8YR3[...]akfs5OI"
}

for the following query (any additional fields of GroupedAssetOutput can be requested)

query {
  asset(groupedAssetId: "a8390ba8-23af-48fa-97dd-79abd944fa2f") {
    __typename
    ... on GroupedAssetOutput {
      name
    }
    ... on BaseAssetErrorInterface {
      message
    }
  }
}

Revoking shared access

To revoke public access to a shared grouped asset, the following mutation shall be used:

mutation {
  unshareGroupedAsset(groupedAssetId: "a8390ba8-23af-48fa-97dd-79abd944fa2f") {
    __typename
    ... on UnsharedGroupedAssetOutput {
      result
    }
    ... on BaseAcsErrorInterface {
      message
    }
  }
}

result will be true if a sharing code has been deactivated, and false otherwise (e.g. in the case where no active sharing codes exist).

After deactivation of a sharing code, trying to access a grouped asset with an existing signature will result in a AssetErrorResourceAccessDeniedOutput, and trying to create a new signature with the deactivated sharing code will result in a AcsErrorEntityNotFoundOutput.

JS-SDK reference

• Account

  Account Services

• Assets

  HxDR Assets