Skip to main content

Service Accounts

Overview​

Service accounts are technical user accounts in Witboost, primarily used to allow external services to authenticate and interact with Witboost APIs securely.

They provide a way for systems and applications to perform automated tasks without requiring a personal user account.

Registration​

Only roles with the platform.users.service-accounts.edit permission can register or edit service accounts.
To create one, go to:

Administration Panel → IAM → Service Accounts

Service Accounts page

When registering a service account, you must provide:

  • Email address (required, used as an identifier, not necessarily linked to an actual email account)
  • Display name (optional)
  • Groups the service account belongs to (optional)

Access Tokens​

Once a service account is created, roles with the platform.users.service-accounts.access-tokens.edit permission can generate an access token for it.

  • Limit: each service account can have only one active access token at a time.
  • Expiration: tokens can optionally have an expiration date.
  • Important: the token is only visible at the time of creation. Be sure to copy and store it securely, as you will not be able to view it again later.

Access Token Generation

Token Management​

  • Revoke: invalidate an existing token.
  • Regenerate: create a new token while automatically invalidating the previous one.
    This is useful if a token is lost or compromised.
    The new token will keep the same expiration date as the original.

    To change the expiration date, revoke the old token and create a new one instead.

Exchanging for JWT Tokens​

Access tokens can be exchanged for short-lived JWT tokens to authenticate API calls.

Endpoint:
POST <witboost-url>/api/auth/access-tokens/jwt

Request body example:

{
  "access_token": "wbat-YY4BMWsHE-tRQ5ZH5HWop_0AjukY4wOPOrx",
  "duration_seconds": 3600,
  "scope": "service:computational-governance"
}

  • scope:
    A space-separated list of scopes that defines what the JWT can do.
    Some Witboost services (e.g., Computational Governance) require specific scopes such as:

    service:computational-governance

  • duration_seconds:
    The lifetime of the generated JWT in seconds.

    • It cannot exceed the remaining lifetime of the original access token.
    • If not provided, a default duration will be used, based on the configuration key:
      ui.appConfig.backend.auth.shortLivedTokenDurationSeconds (default: 5 minutes).
    • It's recommended to keep this value as low as possible for security: invalidating an access token does not invalidate any active short-lived JWTs created from it.
warning

If the provided duration or the default duration exceeds the remaining lifetime of the access token, the JWT creation request will be rejected.

Response body example:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Edit and Removal​

To edit or delete a service account:

  • Navigate to Administration Panel → IAM → Service Accounts
  • Use the context menu next to the account.
note

When a service account is deleted, all its associated access tokens are automatically invalidated.

Limitation​

Service accounts are treated like other users in the platform, but they have an important restriction:
they cannot be assigned as owners or developers of data products or other entities within the platform.

To support this, the Identities Picker provides a configuration option to exclude service accounts from the list of identities in templates, preventing their accidental assignment.