Skip to main content

Service Accounts

A service account is a non-interactive credential for machine-to-machine access to Fused. Where your personal login goes through a browser-based sign-in, a service account is a long-lived token that a program presents directly — no browser, no user session. The token authenticates as your team's environment rather than as an individual user.

Use a service account when a system needs to call Fused without a person present:

  • CI/CD pipelines — run UDFs or invalidate caches as part of a deploy.
  • Backend services — mint short-lived session tokens so your product can embed team-only UDFs.
  • Cron jobs and other automation — scheduled tasks that call the Fused API, such as cache invalidation.
  • Headless servers — any environment where interactive login is impossible.

Service accounts sit alongside the other credentials you may have met:

CredentialWhat it isTypical use
Personal loginBrowser sign-in via Workbench or the Python SDKInteractive development
Canvas shared token (fc_…)Per-canvas token in shared UDF URLsCalling shared UDF endpoints over HTTPS
Session tokenShort-lived token minted for a team-only canvasEmbedding team-only UDFs in external apps
Service account tokenLong-lived machine credential for your team's environmentAutomation: CI/CD, backends, cron

Creating a service account​

Create service accounts from the Integrations & Secrets page in Workbench:

  1. Open Integrations & Secrets from the Workbench sidebar. If you're already inside a canvas, use Quick Actions (Ctrl+K) and search for "Integrations & secrets".
  2. Under Service accounts, click + Create service account.
  3. Give the service account a name and click Create.
important

Your service account token is shown only once, at creation. Copy it to a secure location — a secrets manager or your CI system's secret store. Never share it publicly or commit it to version control.

Name each service account after the system that will use it (for example ci-deploy or prod-embed-backend). One service account per system means you can revoke any one of them without breaking the others.

Using a service account with the Python SDK​

The Python SDK picks up a service account token from two environment variables, checked before any saved login or interactive sign-in:

export FUSED_AUTH_TOKEN_TYPE="Fused-Service-Token"
export FUSED_AUTH_TOKEN="<your-service-account-token>"

With both variables set, every SDK call authenticates as the service account:

import fused

# Authenticates via FUSED_AUTH_TOKEN — no interactive login
my_udf = fused.load("team/my_udf")
result = my_udf()

This also applies to the fused CLI, which uses the same credential chain as the SDK.

warning

A service account authenticates as your team's environment, not as a user. Operations that act on behalf of a user — such as creating or pushing canvases (fused canvas push) — require a personal login and fail with an authentication error under a service account. Use a service account to run UDFs and call environment-scoped APIs.

In a CI system, store the token as a secret and expose it to the job. For example, in GitHub Actions:

jobs:
  run-udf:
    runs-on: ubuntu-latest
    env:
      FUSED_AUTH_TOKEN_TYPE: Fused-Service-Token
      FUSED_AUTH_TOKEN: ${{ secrets.FUSED_SERVICE_ACCOUNT_TOKEN }}
    steps:
      - run: pip install fused
      - run: python -c "import fused; print(fused.load('team/my_udf')())"
note

Running these examples requires a real service account token — create one first.

Using a service account with the REST API​

For callers outside Python, pass the token in the Authorization header using the Fused-Service-Token scheme:

Authorization: Fused-Service-Token <your-service-account-token>

The service account can then call Fused API endpoints on behalf of your team's environment. Two common flows:

Minting session tokens — the embed flow for team-only canvases. Your backend exchanges the service account token for a short-lived session token that is safe to hand to a browser:

curl -X POST \
  -H "Authorization: Fused-Service-Token $FUSED_SERVICE_ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 3600}' \
  "https://www.fused.io/server/v1/session-token/by-access-token/<canvas_token>"

The ttl is in seconds — it defaults to 3600 (1 hour) and can be at most 86400 (24 hours). The response includes the session_token and its expires_at time. See Securing Shared Tokens for the full embed authentication flow, including a Python version of this request.

Cache invalidation — refresh cached UDF results from CI/CD or a cron job, authenticated with the same header. See Cache invalidation for the endpoint and examples.

The same Authorization header authenticates the service account to other Fused REST API endpoints as well — any operation available to your team's environment, such as loading UDFs or running them over HTTP. Endpoints that act on behalf of a user (for example creating or updating canvases) require a personal login.

Managing and revoking service accounts​

The Service accounts section of Integrations & Secrets lists your team's existing service accounts with their names and creation dates. The token itself is not retrievable after creation — if a token is lost, create a new service account.

To revoke a service account, delete it from the same page.

To rotate a service account, create a new service account, move consumers to the new token, then delete the old one.

danger

Deleting a service account invalidates its token immediately. Any system still using it will start failing with authentication errors.

Security best practices​

  • Store the token as a secret. Use a secrets manager or your CI system's secret store — never code, docs, or version control. If you need the token inside a UDF, store it with Fused secrets management.
  • One service account per system. A leaked or decommissioned integration then only requires revoking one token.
  • Never ship the service account token to a client. Browsers and client apps should only ever receive short-lived session tokens minted by your backend.
  • Treat it as a team-level credential. A service account authenticates as your team's environment, not as an individual user — anyone holding the token can act with that access.

See also​