Exchange a workload token

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/oauth/token

Trade a short-lived OIDC token from your platform (GitHub Actions, a cloud provider, Kubernetes) for a Syntic access token that acts as a service account. No API key is sent: the incoming JWT is the credential. The body may be JSON, as below, or application/x-www-form-urlencoded.

For how this fits into a full workflow, see Workload identity.

Headers

Header	Required	Value
`syntic-beta`	Yes, while in preview	`token-exchange-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`

Body parameters

Parameter	Type	Required	Notes
`grant_type`	string	Yes	`urn:ietf:params:oauth:grant-type:token-exchange`
`subject_token`	string	Yes	The signed OIDC token (a JWT) your platform gave the workload.
`subject_token_type`	string	Yes	`urn:ietf:params:oauth:token-type:jwt`
`service_account`	string	Yes	The service account id, starting with `svcacct_`.
`requested_lifetime_seconds`	integer	No	60 to 3600, capped by the trust rule. Default 900.

Response

200 OK, Content-Type: application/json

{
  "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"
}

Field	Type	Description
`access_token`	string	Starts with `sat_`. Send it as `Authorization: Bearer ...` until it expires.
`token_type`	string	Always `Bearer`.
`expires_in`	integer	Seconds until the token stops working.
`service_account`	string	The service account the token acts as.
`workspace_id`	string	The workspace billed for its requests.

Examples

curl -sS https://app.syntic.ai/v1/oauth/token \
  -H "syntic-beta: token-exchange-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{
      "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
      "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
    }'

import requests
 
resp = 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": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7",
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/oauth/token', {
  method: 'POST',
  headers: {
    'syntic-beta': 'token-exchange-2026-11-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/oauth/token", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("syntic-beta", "token-exchange-2026-11-01")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
              "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
              "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
              "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/oauth/token"))
            .header("syntic-beta", "token-exchange-2026-11-01")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/oauth/token");
request.Headers.Add("syntic-beta", "token-exchange-2026-11-01");
request.Content = new StringContent("""
    {
      "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
      "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
      "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
      "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
  "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
  "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/oauth/token');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'syntic-beta: token-exchange-2026-11-01',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true));

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/oauth/token")
req = Net::HTTP::Post.new(uri)
req["syntic-beta"] = "token-exchange-2026-11-01"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ii4uLiJ9...",
    "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "service_account": "svcacct_01JCB3D5F7H9K1M3P5R7"
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(JSON.parse(res.body))

Errors

This endpoint follows the OAuth 2.0 error format so standard libraries understand it: {"error": "invalid_grant", "error_description": "...", "request_id": "req_..."}. The type column below is empty because the OAuth error string is the code.

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
400	—	`invalid_request`	A required field is missing or malformed.
400	—	`unsupported_grant_type`	`grant_type` is not token exchange.
400	—	`invalid_grant`	Signature, expiry, issuer, audience or claims match no trust rule. The description names the first mismatch and never echoes the token.
401	—	`invalid_client`	The service account does not exist or is disabled.
429	—	`slow_down`	More than 60 exchanges per minute for one service account.

Using the access token

sat_ tokens cannot be refreshed or revoked one by one. Exchange a fresh JWT when one expires; to cut off access immediately, disable the service account or its trust rule. Calls made with the token are billed to the service account’s workspace and recorded in the audit log under its name.

Revoke a sign-in Get the signed-in user

Was this page helpful?