Skip to content

Service accounts

Introduction

The Service accounts tab of the Administration dashboard allows users belonging to the Owner role to manage service accounts.
Service accounts are identities that software programs impersonate to make authorized calls to the Platform's back office API. The back office API is the one described in the Swagger UI page accessible from the user menu.

Note

Service accounts are not used for authenticating NL Flow API calls, NL Flow API authentication is based on API keys.

The authentication mechanism is OAuth 2.0 with the Client Credentials grant type.
In OAuth 2.0 jargon, a Platform service account is a registered client application. The data to be specified to obtain the authorization token are therefore:

  1. The client ID
  2. The client secret

The token must be requested at the URL that corresponds to the value of the Access Token URL property of the account.

Apart from the authentication mechanism, service accounts are users like the others: they can belong to the same roles, human users can share projects with them, they are owners of the projects they create programmatically and, also programmatically, if they belong to the Owner role, they can change the ownership of projects and corpora.

Add a new service account

To add a new service account:

  1. Select New service account in the Service accounts panel.

  2. In the Create service account panel, enter account data and role then select Create.

    A confirmation dialog displays the client secret.

  3. Select Copy to clipboard to copy the client secret to the clipboard, then paste it in a safe place.

    Warning

    The client secret is displayed just once after the creation of the service account, it cannot be recovered later, so it is necessary to save it while it's displayed.

Search for an account

To search for an account enter the search criteria in the search box in the Service accounts panel, then press Enter.

To reset the search criteria, select the X icon inside the search box.

Filter accounts

To filter the list of accounts based on the role, choose from the Roles dropdown menu in the Service accounts panel.

To filter the list of accounts based on their status—either active or disabled—, choose from the Show dropdown menu in the Service accounts panel.

The icon of active accounts has a green dot beside it, while the icon of accounts that have been disabled has a red dot.

Active accounts Disabled accounts

Edit and delete an account

To edit or delete an account, select it in the Service accounts panel, then, in the Edit service account panel on the right:

  • To change the user's role, select the new role from the Role dropdown menu.
  • To disable and re-activate the account, use the User activation toggle switch.
  • To generate a new client secret, select Regenerate. A confirmation dialog displays the client secret. Select Copy to clipboard to copy the client secret to the clipboard, then paste it in a safe place.
  • To copy the URL by which a client application can get authorization tokens, select Copy url to clipboard beside Access Token URL.
  • To copy the URL of the issuer of the authorization tokens, select Copy url to clipboard beside Issuer URL.
  • To delete the user's account, select Delete.

Select Save to save any changes.

When you delete a service account, all the corpora and projects owned by the account will be removed, including those shared with other users. To avoid the loss of projects and corpora:

  1. Disable the account.
  2. Set a new owner for the projects and corpora (see below).
  3. Delete the service account.

If you select a user that's been disabled from the Service accounts panel, three tabs appear on the right side:

  • Information: account information
  • Projects: "lonely" projects belonging to the disabled account
  • Corpora: "lonely" corpora belonging to the disabled account

Manage lonely projects and corpora

In the lists inside Projects and Corpora tabs the TV column of the list shows the tech version the project or corpus is based upon. The green dot in the Status column indicates that no analysis or loading operations are in progress.

  • To change the sort order select the header of any column except Owner.
  • To toggle the list of the users—that is the owner plus the collaborators the project or corpus is shared with—of a project or corpus, select the expand and the collapse icons to the left of the project row.

  • To give the ownership of a project or corpus to a collaborator:

    1. Expand the project or corpus row as explained above.
    2. In the Collaborators list, select Set as owner below the collaborator's name.
    3. Select Confirm.

  • To give the ownership of a project to a user that is not a collaborator:

    1. Select the project or corpus, then select Set new owner.
    2. In the Set new project owner dialog (for a project) or Set new corpus owner dialog (for a corpus), type the user's name.
    3. Select Save.

  • To get information about the tech version of the project or corpus, hover over the tech version icon.

  • To start the creation wizard for a knowledge graph customization project based on the tech version of a project or corpus, hover over the tech version icon row and select Knowledge Graph Customization.