Create a trust rule

⚠️

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

POST https://app.syntic.ai/v1/organizations/service_accounts/{service_account_id}/trust_rules

Allow tokens from an external identity provider to act as this service account through token exchange. Rules are checked on every exchange; the first enabled rule whose issuer, audience and every condition match wins.

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

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <admin key>`: an Admin API key (`sk_admin_...`). Inference keys are refused with `403 admin_key_required`. See Admin API keys.
`syntic-beta`	Yes, while in preview	`admin-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of acting twice. See Idempotency.

Path parameters

Parameter	Type	Description
`service_account_id`	string	The service account id, starting with `svcacct_`.

Body parameters

Parameter	Type	Required	Notes
`issuer`	string	Yes	Issuer URL, exactly as it appears in the token’s `iss` claim.
`audience`	string	Yes	Usually `https://app.syntic.ai`.
`conditions`	object	Yes	Up to 10 claim conditions.
`max_token_lifetime_seconds`	integer	No	Default 3,600.
`status`	string	No	`enabled` (default) or `disabled`.

Response

201 Created, Content-Type: application/json

{
  "id": "frule_01JCK9M1P3R5T7V9X1Z3",
  "type": "trust_rule",
  "service_account_id": "svcacct_01JCH7K9M1P3R5T7V9X1",
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://app.syntic.ai",
  "conditions": {
    "repository": "acme/billing",
    "ref": "refs/heads/main"
  },
  "max_token_lifetime_seconds": 900,
  "status": "enabled",
  "last_matched_at": null,
  "created_at": "2026-10-20T09:05:00Z"
}

Field	Type	Description
`issuer`	string	Must be a preset issuer or one registered under federation issuers.
`audience`	string	The `aud` the incoming token must carry.
`conditions`	object	Claim name to required value. A trailing `*` matches any suffix. At least one condition is required.
`max_token_lifetime_seconds`	integer	60 to 3,600. Syntic tokens issued under this rule never outlive it.
`status`	string	`enabled` or `disabled`.
`last_matched_at`	string or null	Last successful exchange under this rule.

Examples

curl -sS "https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules" \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "syntic-beta: admin-2026-11-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "issuer": "https://token.actions.githubusercontent.com",
      "audience": "https://app.syntic.ai",
      "conditions": {
        "repository": "acme/billing",
        "ref": "refs/heads/main"
      },
      "max_token_lifetime_seconds": 900
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_ADMIN_KEY']}",
        "syntic-beta": "admin-2026-11-01",
        "Idempotency-Key": "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69",
    },
    json={
        "issuer": "https://token.actions.githubusercontent.com",
        "audience": "https://app.syntic.ai",
        "conditions": {
            "repository": "acme/billing",
            "ref": "refs/heads/main"
        },
        "max_token_lifetime_seconds": 900
    },
    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/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_ADMIN_KEY}`,
    'syntic-beta': 'admin-2026-11-01',
    'Idempotency-Key': '8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://app.syntic.ai",
    "conditions": {
      "repository": "acme/billing",
      "ref": "refs/heads/main"
    },
    "max_token_lifetime_seconds": 900
  }),
})
const text = await res.text()
const data = text ? JSON.parse(text) : null
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data ?? res.status)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://app.syntic.ai",
  "conditions": {
    "repository": "acme/billing",
    "ref": "refs/heads/main"
  },
  "max_token_lifetime_seconds": 900
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_ADMIN_KEY"))
	req.Header.Set("syntic-beta", "admin-2026-11-01")
	req.Header.Set("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
	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 = """
            {
              "issuer": "https://token.actions.githubusercontent.com",
              "audience": "https://app.syntic.ai",
              "conditions": {
                "repository": "acme/billing",
                "ref": "refs/heads/main"
              },
              "max_token_lifetime_seconds": 900
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_ADMIN_KEY"))
            .header("syntic-beta", "admin-2026-11-01")
            .header("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
            .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/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_ADMIN_KEY"));
request.Headers.Add("syntic-beta", "admin-2026-11-01");
request.Headers.Add("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69");
request.Content = new StringContent("""
    {
      "issuer": "https://token.actions.githubusercontent.com",
      "audience": "https://app.syntic.ai",
      "conditions": {
        "repository": "acme/billing",
        "ref": "refs/heads/main"
      },
      "max_token_lifetime_seconds": 900
    }
    """, 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'
{
  "issuer": "https://token.actions.githubusercontent.com",
  "audience": "https://app.syntic.ai",
  "conditions": {
    "repository": "acme/billing",
    "ref": "refs/heads/main"
  },
  "max_token_lifetime_seconds": 900
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_ADMIN_KEY'),
        'syntic-beta: admin-2026-11-01',
        'Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
        '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) ?? $status);

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/organizations/service_accounts/svcacct_01JCH7K9M1P3R5T7V9X1/trust_rules")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_ADMIN_KEY')}"
req["syntic-beta"] = "admin-2026-11-01"
req["Idempotency-Key"] = "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "https://app.syntic.ai",
    "conditions": {
      "repository": "acme/billing",
      "ref": "refs/heads/main"
    },
    "max_token_lifetime_seconds": 900
  }
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 res.body.empty? ? res.code : JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
400	`invalid_request_error`	`conditions_required`	No condition besides issuer and audience; such a rule would trust every identity on the provider.
400	`invalid_request_error`	`unknown_issuer`	The issuer is neither a preset nor registered.
409	`conflict_error`	`trust_rule_limit_reached`	The account already has 20 rules.
404	`not_found_error`	`service_account_not_found`	No service account with this id in the organization.
401	`authentication_error`	`invalid_api_key`	The admin key is missing, unknown, revoked or expired.
403	`permission_error`	`admin_key_required`	An inference key was used.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Unarchive List rules

Was this page helpful?