Share:

  Accessing the API

There are two recommended ways, authenticate user against the FireStart API, using the default credentials of the logged in user or using a personal access token (PAT)

Default Credentials

When using the Windows with Active Directory authentication, the default credentials (currently logged in Windows user) can be handed over, using the -UserDefaultCredentials option, e.g.

irm -Uri https:/<server>/api/task/fpp?userOnly=false -UseDefaultCredentials

Personal Access Token (PAT)

For Windows with Active Directory authentication, PAT can be used, for other authentication methods (Azure Active Directory, ADFS), PAT must be used.

Generate a PAT using the FireStart Client

  1. In the FireStart Client, click the UserIcon in the Header Bar and then Personal Access Token.

  2. This will open a browser window where the lifetime of the token can be definded (defaults is 90 days). Press 'Generate access token'.

  3. Copy the generated token. It will not be shown again.

  4. Use the token in scripts

Generate a PAT using the FireStart ProcessPortal

  1. In the browser, open the URL https://<ProcessPortalURL>/auth/firestartuser
  2. Click 'View PAT'

  3. In the next screen, the lifetime of the token can be defined (default is 90 days). Press 'Generate access token'.
  4. Copy the generated token. It will not be shown again.
  5. Use the token in scripts
Information The call to the API will be executed in the context of the user generating the token. Only results for which the user has permissions will be returned.

Revoke a PAT

If a PAT has been created and you would like to revoke it (or see the expiration date), follow the steps of generating a PAT. If a user is having a PAT, instead of generation, a revoke message will be shown.

Warning If a PAT has been revoked, scripts using it will no longer be able to access the API. If a new PAT is generated, the revoked token must be replaced in all scripts with the new one.

Using the PAT

$token = "e49b68ded927bd4ede6e6ccf4bf989b671ec20ffa81682dbf043d1db3b59dcbb"
irm -Uri https:/<server>/api/task/fpp?userOnly=false -Header @{"authorization"="bearer $token"}

Best practice for use within a workflow

To be able to easily update the access token(s) for all Workflows it is recommended to generate a abstract BE and use this in the workflow(s).