Zero-Trust Identity

Turn's grant identity primitive enforces a strict security boundary: the LLM agent requests an opaque Identity capability handle, and the Turn VM (the secure Rust host) manages the actual OAuth tokens, API keys, and secret storage. The agent's memory only ever holds an unforgeable reference, never the raw credential.

When the Identity handle is passed through the Standard Library's net.get or net.post, the Turn Standard Library validates the capability at the language level, then the VM's kernel trap intercepts the request at the HTTP boundary, looks up the real bearer token from the host environment (following the convention TURN_IDENTITY_<PROVIDER>_TOKEN), and injects the Authorization: Bearer header automatically. If the environment variable is not configured, the VM returns an explicit error rather than silently failing.

secure_identity.tn

let net = use "std/net";

// Request an opaque identity capability from the VM host.
// The raw OAuth token never enters the agent's memory.
let stripe_auth = grant identity::oauth("stripe");

// Make an authenticated call via the Standard Library network module.
// The Turn VM intercepts at the HTTP boundary, retrieves the real
// token from the host environment, and injects the Bearer header.
let customers = net.get({
  "url":      "https://api.stripe.com/v1/customers",
  "identity": stripe_auth
});

call("echo", "Customers: " + customers);

// The same pattern works for any provider.
let google_auth = grant identity::oauth("google_workspace");
let events = net.get({
  "url":      "https://www.googleapis.com/calendar/v3/users/me/calendarList",
  "identity": google_auth
});

call("echo", "Calendar: " + events);

Run it:

export TURN_IDENTITY_STRIPE_TOKEN=sk_live_...
export TURN_IDENTITY_GOOGLE_WORKSPACE_TOKEN=ya29...
turn run secure_identity.tn

The Identity type is opaque by design. It cannot be coerced to a string, serialized to JSON, or echoed to stdout. Any attempt to use it as a value outside of the identity field in an HTTP tool call will result in a runtime error. This guarantees that even if an LLM hallucinates a call("echo", auth) instruction, the secret is never leaked.

Zero-Trust Identity

Next Steps