Workload identity

Workload identity federation lets your automated systems (CI pipelines, cloud functions, Kubernetes pods) call the Syntic API without a stored API key. Instead, the workload proves who it is with a short-lived token from an identity provider it already trusts, such as GitHub Actions or your cloud provider, and trades it for a Syntic access token that expires within the hour.

There is no long-lived secret to leak, rotate or forget in a repository. Access ends on its own within the hour.

When to use it

How it works

1. An Administrator creates a service account in a workspace and a trust rule that says which external identities may act as it: the identity provider’s issuer URL, the expected audience, and conditions on the token’s claims (for example, repository must be acme/billing and ref must be refs/heads/main).
2. At run time, your workload gets an OIDC token (a signed JWT) from its platform.
3. It calls POST /v1/oauth/token with that JWT.
4. Syntic checks the signature against the issuer’s published keys, checks expiry and audience, matches the trust rules, and returns a Syntic access token valid for up to one hour.
5. The workload uses that token as Authorization: Bearer ... on any API call the service account is allowed to make.

Requests made this way are billed to the service account’s workspace and appear in usage and audit logs under the service account’s name.

Supported identity providers

Set it up

{
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://app.syntic.ai",
  "conditions": {
    "repository": "acme/billing",
    "ref": "refs/heads/main"
  },
  "max_token_lifetime_seconds": 900
}

The token endpoint

POST /v1/oauth/token

No API key is needed: the incoming JWT is the credential. Send syntic-beta: token-exchange-2026-11-01 while in preview. The body may be JSON or application/x-www-form-urlencoded.

Response 200 OK:

{
  "access_token": "sat_eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7",
  "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q"
}

Access tokens start with sat_. Use them exactly like an API key until expires_in runs out, then exchange a fresh JWT. They cannot be refreshed or revoked individually; disable the service account or its trust rule to cut off access at once.

# .github/workflows/summarise.yml
permissions:
  id-token: write   # lets the job request an OIDC token
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Get a Syntic token
        run: |
          JWT=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://app.syntic.ai" | jq -r .value)
          TOKEN=$(curl -sS https://app.syntic.ai/v1/oauth/token \
            -H "syntic-beta: token-exchange-2026-11-01" \
            -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
            -d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
            -d service_account=svcacct_01JCB3D5F7H9K1M3P5R7 \
            --data-urlencode subject_token="$JWT" | jq -r .access_token)
          echo "::add-mask::$TOKEN"
          echo "SYNTIC_API_KEY=$TOKEN" >> "$GITHUB_ENV"

// jwt comes from your platform, e.g. a projected Kubernetes token file
import { readFile } from 'node:fs/promises'
 
const jwt = (await readFile('/var/run/secrets/syntic/token', 'utf8')).trim()
const res = await fetch('https://app.syntic.ai/v1/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'syntic-beta': 'token-exchange-2026-11-01' },
  body: JSON.stringify({
    grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
    subject_token: jwt,
    subject_token_type: 'urn:ietf:params:oauth:token-type:jwt',
    service_account: 'svcacct_01JCB3D5F7H9K1M3P5R7',
  }),
})
const { access_token, expires_in } = await res.json()

import requests
import google.auth.transport.requests
from google.oauth2 import id_token
 
# On Google Cloud: fetch an identity token for the Syntic audience
jwt = id_token.fetch_id_token(google.auth.transport.requests.Request(), "https://app.syntic.ai")
 
tok = requests.post(
    "https://app.syntic.ai/v1/oauth/token",
    headers={"syntic-beta": "token-exchange-2026-11-01"},
    json={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": jwt,
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7",
    },
).json()
headers = {"Authorization": f"Bearer {tok['access_token']}"}

Errors

Token endpoint errors follow the OAuth 2.0 format so standard libraries understand them, plus the Syntic request_id:

{ "error": "invalid_grant", "error_description": "Token claim 'repository' does not match any trust rule.", "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d" }

Calls made with the resulting sat_ token return the normal error envelope; an expired token gives 401 authentication, code expired_token.

Audit

Every exchange writes an audit event, service_account.token_issued, with the issuer, the matched rule and the token’s sub claim, so you can trace any API call back to the exact CI run or pod that made it.

Build notes for the platform team

• Reuse the JWT verification and JWKS caching from single sign-on; cache keys per issuer for 10 minutes and refetch on unknown kid.
• sat_ tokens are signed JWTs verified at the edge without a database read; embed workspace, service account, scopes and expiry.
• Store trust rules per service account; evaluate every rule and accept on the first full match.

Related

• Managing API keys
• Workspaces
• Audit events