Skip to main content

Service Account Token (SAT)

Feature availability

Service Account Tokens must be enabled for your organization. Contact your Viven representative or support@viven.ai to get this feature turned on.

A Service Account Token (SAT) is an admin-created access token meant for programmatic/server-side use cases, where a system needs to call Digital Twin APIs without relying on an interactive "log in via browser" flow.

This is different from a Personal Access Token (PAT), which is meant for an individual user's personal/programmatic usage.

Where SATs live in the Admin Console​

SAT management is implemented as an Admin Console experience (i.e., created/managed by admins).

In the token system work, we added an Admin API Tokens page that supports SAT management (create/revoke, etc.) and is permission-guarded.

How SAT authentication works at request time​

When a client calls our APIs using an SAT:

  • The client sends the SAT as a bearer token in the request (i.e., token-based auth).
  • Our backend verifies SATs (and PATs) before servicing the request.
  • SATs are enforced with scopes/ACL checks (the token system includes explicit checks for scopes and user ACL).

SAT user impersonation​

SATs support user impersonation, so an admin/system can run an API request "as" a specific end user, which is useful when a machine workflow needs to act on behalf of a user.

Mechanically, this is done via a request header:

  • The caller includes a dt-viven-user header to indicate which user to impersonate.
  • The system verifies the SAT and then applies impersonation logic accordingly (and tracks impersonation context).
Authorization: Bearer <service_account_token>
dt-viven-user: user@company.com

Who can manage SATs (permissions)​

SAT management is restricted to admin roles with the right permission. The token work added a dedicated permission — see Digital Twin Roles for details on perm_dt_manage_api_tokens.

When SATs are the right tool​

SATs are especially useful when:

  • You're enabling programmatic usage (scripts/agent frameworks) where a browser OAuth flow is awkward.
  • You need central automation set up by an admin (vs. each user managing their own PAT).

Operational caution​

Because SAT regeneration/rotation can break integrations that depend on that token, we treat token rotation as an operational event.