Portal users

SBS Portal users are people in your organization that need to interact with Socrate Business Services at tenant or application level. This includes, for example, the support personnel, who may need to view, monitor, or occasionally modify SBS data for a particular application and tenant.

The interface where tasks such as the ones above are performed is provided by the SBS Portal website (https://portal.socrate.io). For an introduction to the portal, see SBS Portal.

From the SBS Console, you can add SBS Portal users and configure their permissions. The permissions you define for each portal user dictate what services that user will be able to see and query after they sign in to the portal.

View portal users

You can view the portal users defined for your organization as follows:

1. If you haven’t done that already, sign in to the SBS Console.
2. If there are multiple SBS accounts in your organization, select the account of interest from the accounts list in the top-right corner of the page.
3. Click the WebUI tab.
4. Click Portal Users in the navigation menu on the left-hand side.

If you prefer to use GraphQL, run the following query in the GraphQL tab:

query portalUsers {
  portalUsers {
    items {
      userId
      provider
      email
      name
      picture
      createdAt
      permissions{
        appId
        app {
          name
        }
        tenantId
        tenant {
          name          
        }
        scope
        createdAt
      }
    }
  }
}

To run this query, you must either be logged into a root user account, or be an account user with permissions to run this query.

Add portal users

After the user has signed in to the SBS Portal once, you can proceed to actually adding them as portal users, as follows:

1. Sign in to the SBS Console.
2. If your organization has multiple SBS accounts, select the account to which you would like to add the user from the accounts list in the top-right corner of the page.
3. Click the WebUI tab.
4. Click Portal Users in the navigation menu on the left-hand side.
5. Click New Portal User. A dialog box pops up.
6. Enter the user’s email address. Be aware that this must be either a Google or Microsoft email address and the respective person must have logged into the SBS Portal at least once.
7. Click Add.

If you prefer to add portal users through GraphQL, take the following steps:

1. Sign in to the SBS Console.
2. From the accounts list in the top-right corner of the page, select the account to which you would like to add the portal user.
3. Click the GraphQL tab.
4. Enter the following mutation:

mutation addPortalUser($input: AddPortalUserInput!) {
  addPortalUser(input: $input) {
    userId
    provider
    email
    name
    createdAt
  }
}

In the Variables section, make sure to replace the example email provider and address as required:

{
  "input": {
    "provider": "GOOGLE",
    "email": "SOME_GOOGLE_EMAIL"
  }
}

Add or update portal user permissions

You can add or update the permissions (scope) of an existing portal user as follows:

1. If you haven’t done that already, sign in to the SBS Console.

2. From the accounts list in the top-right corner of the page, select the account of interest.

3. Click the WebUI tab.

4. Click Portal Users in the navigation menu on the left-hand side.

5. Click the portal user whose permissions you would like to set.

6. Do one of the following:

   • To add a new permission, click in the top-right corner of the Permissions grid. A dialog box opens.
   • To update an existing permission, click Edit next to the relevant permission record on the grid.

7. In the Scope field, enter the extent of permissions (scope) that should be available to the portal user, and then click Save. For details, see Scope editor.

   

In the example above, the portal user is assigned the following permissions, in the Visual mode:

• read data from the organizations-api (query)
• read and write data in the ro-efactura-api (query, mutation)
• read and write data in the ro-anaf-oauth-api (query, mutation)

If there are permissions already set for this application and tenant combination, a warning message appears on the dialog box, for example:

In this case, you can do one of the following:

• Close the dialog box without taking any action. This will leave the existing portal users permissions intact.
• If you would like to overwrite the existing permissions with the ones defined on the dialog box, click Save.

Setting permissions through GraphQL

If you prefer to use GraphQL, run the setPortalUserPermission mutation from the GraphQL tab, for example:

mutation setPortalUserPermission($userId: ID!, $permission: PermissionInput!) {
  setPortalUserPermission(userId: $userId, permission: $permission) {
    userId
    provider
    email
    name
    picture
    createdAt
    permissions {
      appId
      app { name }
      tenantId
      tenant { name }
      scope
      createdAt
    }
  }
}

In the Variables section, make sure to replace the arguments as required:

{
    "userId": "PORTAL_USER_ID",
    "permission": {
        "appId": "APPLICATION_ID",
        "tenantId": "TENANT_ID",
        "scope": "email-api:query:* email-api:mutation:* file-management-api:query:* file-management-api:mutation:*"
     }
}

In the mutation above, the scope parameter is set to email-api:query:* email-api:mutation:* file-management-api:query:* file-management-api:mutation:*, which means that the portal user will have permissions to all queries and all mutations of the Email Service and File Management Service.

Remove portal user permissions

To remove existing permissions of a portal user for particular account, app, or tenant, do the following:

1. Click the portal user.
2. In the Permissions grid, click Delete next to the permission that is to be removed.

If you prefer to use GraphQL, run the removePortalUserPermission mutation from the GraphQL tab, for example:

mutation removePortalUserPermission($userId: ID!, $permissionKey: PermissionKeyInput!) {
  removePortalUserPermission(userId: $userId, permissionKey: $permissionKey) {
    userId
    provider
    email
    name
    picture
    createdAt
    permissions {
      appId
      app { name }
      tenantId
      tenant { name }
      scope
      createdAt
    }
  }
}

In the Variables section, make sure to replace the arguments as required:

{
    "userId": "PORTAL_USER_ID",
    "permission": {
        "appId": "APPLICATION_ID",
        "tenantId": "TENANT_ID"
     }
}

Remove portal users

You can delete portal users as follows:

1. If you haven’t done that already, sign in to the SBS Console.
2. From the accounts list in the top-right corner of the page, select the account of interest.
3. Click the WebUI tab.
4. Click Portal Users in the navigation menu on the left-hand side.
5. Click Delete next to the portal user you would like to delete, and confirm your action when prompted.

If you prefer to delete portal users through GraphQL, run:

mutation removePortalUser($userId: ID!) {
  removePortalUser(userId: $userId) {
    userId
    provider
    email
    name
    createdAt
  }
}

In the Variables section, make sure to replace the ID of the portal user as required:

{
    "userId": "YOUR_PORTAL_USER_ID"
}