Authenticate with a service account

Automation — CI pipelines, deploy scripts, infrastructure-as-code — needs to call the LinkMesh API without a human in the loop. Rather than hard-coding a person’s password (which breaks when they rotate it or leave), create a service account: a named, non-human identity that owns long-lived API tokens scoped to exactly the permissions the automation needs.

A token is a bearer credential of the form lmsat_…. You send it in the Authorization header; LinkMesh resolves it to its service account’s permissions and enforces them with the same RBAC rules as a human login.

Caution

A token is shown once, at mint time. Copy it then — LinkMesh stores only a hash and can never display it again. Lost a token? Rotate it (below).

Create a service account and mint a token

You need an administrator login (service-account management is admin-only by default).

1. Open Settings → Service Accounts and click Create Service Account. Give it a lowercase, hyphenated name that says what it’s for — e.g. gitlab-ci, terraform, backup-runner.

2. Pick its permissions. The scope picker groups permissions by resource (collectors, pipelines, sources, …). Select the minimum the automation needs — a deploy pipeline that only reads fleet status needs collectors:read, nothing more. You can only grant permissions you hold yourself.

3. Mint a token. Expand the account and click the key icon. Give the token a label (e.g. ci-main), choose an expiry (7/30/90 days, 1 year, or never), and Mint. The next screen shows the raw lmsat_… value once — copy it now.

Use the token

Send it as a Bearer token against …/api/v1. List collectors:

curl -H "Authorization: Bearer $LINKMESH_TOKEN" \
  https://linkmesh.example.com/api/v1/collectors

Create a pipeline (the token needs pipelines:create):

curl -X POST \
  -H "Authorization: Bearer $LINKMESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"drop-debug","description":"drop debug logs"}' \
  https://linkmesh.example.com/api/v1/pipelines

In CI, put the token in a masked/protected variable and read it from the environment — never inline it in a command or check it into a repo:

# GitLab CI / GitHub Actions — token comes from a secret, not the YAML
export LINKMESH_TOKEN="$LINKMESH_API_TOKEN"
curl -fsS -H "Authorization: Bearer $LINKMESH_TOKEN" \
  https://linkmesh.example.com/api/v1/collectors

Tip

Every token’s effective permissions are listed on its service account. To see what a token can do, check the account in Settings → Service Accounts.

Rotate a token

Rotation issues a fresh token and revokes the old one in a single step, keeping the same label and scope — use it on a schedule, when a token nears expiry, or immediately if one may have leaked.

1. Expand the service account, find the token, and click the rotate icon.

2. Copy the new lmsat_… value from the reveal screen.

3. Update the secret your automation reads from (CI variable, secret manager), then re-run. The old token stops working as soon as rotation completes.

To retire a token without a replacement, use revoke (the trash icon) — the token stops authenticating immediately. Deleting a service account revokes all of its tokens.

Note

Expired tokens are rejected at once, and a background sweep also marks them revoked so they show as inactive in the UI. You don’t need to clean them up manually.

Common errors

All API errors come back as { "success": false, "error": "…" } with an HTTP status:

Symptom	HTTP	Cause	Fix
API token expired	401	The token passed its expiry	Mint or rotate a token
API token revoked	401	The token (or its account) was revoked/deleted	Mint a new token under an active account
Service account is disabled	401	The owning account was deactivated	Re-activate the account, or use another
Insufficient permissions	403	The token’s scope doesn’t include this action	Grant the permission to the account and mint a new token
API token not recognised	401	Wrong/garbled token value	Check the Authorization: Bearer … header

Note

Permissions are captured when the token is minted. Widening a service account’s permissions does not widen tokens issued earlier — mint a new token (or rotate) to pick up the new scope.

Security best practices

• Least privilege. Scope each account to the smallest permission set its job needs. Use separate accounts for separate jobs so you can revoke one without breaking the others.
• Never commit tokens. Keep them in CI secrets / a secret manager and read them from environment variables at run time.
• Set an expiry on tokens used by short-lived or experimental automation; reserve never-expiring tokens for long-running, well-guarded systems.
• Rotate on a schedule and immediately on suspected exposure.
• Audit. Service-account and token activity is recorded in the audit log (Settings → Audit Log) — filter by the account to review what a token did.