Skip to main content

API Token ABAC Profiles: Choosing the Right Keeptrusts Credential

Keeptrusts no longer needs two separate mental buckets such as "access key" and "gateway key." The platform uses one API-token system. What makes one token safe for app traffic and another safe for hosted gateway runtime identity is the ABAC profile attached to the token.

Use this page when​

  • You are deciding what credential a web app, backend service, IDE, or hosted gateway runtime should use.
  • You want to explain token differences without teaching a legacy label taxonomy.
  • You need a practical way to reason about blast radius, storage, and rotation.

Primary audience​

  • Primary: Technical Engineers and Platform Operators
  • Secondary: Security teams and Technical Leaders

The problem​

Credential confusion usually starts with a false assumption: if two secrets look similar, they must be interchangeable. In Keeptrusts, that is not true.

Two tokens may both be kt_live_... values and still have different authorization outcomes because policy evaluates:

  • purpose
  • principal_type
  • bindings such as gateway_id, team_id, provider filters, model filters, or budgets

That is why an app-side token can be correct for curl while a hosted gateway runtime token is correct for KEEPTRUSTS_API_TOKEN, even though both are API tokens.

The ABAC explanation​

The useful question is not "which key type is this?" It is "which workload identity was encoded into this token?"

Common profiles​

WorkloadABAC profileWhy it exists
App, script, IDE, browser, or curl calling the gatewaypurpose=general, principal_type=api_tokenLets the workload send governed requests through the gateway
Hosted gateway runtimepurpose=gateway_runtime, principal_type=gateway_runtime, bindings.gateway_id=<gateway-id>Lets the gateway process identify itself to the control plane
Machine integrationpurpose=integration, principal_type=api_tokenGives server-side automation a durable machine identity with explicit bindings

Older docs may refer to the first profile as an "access key" and the second as a "gateway key." Those labels are shorthand for ABAC profiles, not separate credential technologies.

Why the distinction matters​

1. Different policy decisions​

The ABAC engine can allow one token to execute gateway requests while denying another, even if both are valid token strings.

2. Different storage locations​

An app-side gateway token may live in a browser-safe or client-safe integration boundary. A hosted gateway runtime token belongs in infrastructure secret storage and should never be copied into frontend or IDE clients.

3. Different bindings​

A hosted runtime token is often bound to one gateway instance. A client token may be bound to a team, provider, model set, or budget instead.

4. Different incident response​

If a credential leaks, knowing the token's ABAC profile tells you immediately whether the blast radius is client traffic, runtime identity, or a server-side integration workflow.

Practical rule set​

  • If the caller is an app, edge function, IDE, or backend service sending governed traffic through the gateway, use an API token minted for gateway request execution, usually purpose=general.
  • If the caller is the gateway process itself, use an API token minted for hosted runtime identity, usually purpose=gateway_runtime.
  • If the need is console access or privileged control-plane reads, use the proper bearer-token or session flow instead of stretching an API token beyond its intended boundary.

Example​

App-side gateway call​

curl https://gateway.keeptrusts.example/v1/chat/completions \
  -H "Authorization: Bearer $KEEPTRUSTS_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "Summarize the latest escalations." }
    ]
  }'

That token should be a gateway-client token, typically purpose=general.

Hosted gateway runtime​

export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
export KEEPTRUSTS_API_TOKEN="kt_live_..."

That token should be a hosted-runtime token, typically purpose=gateway_runtime.

Results and impact​

Teams that choose tokens by ABAC profile rather than legacy label get a cleaner mental model:

  • one API-token system
  • explicit workload identity
  • narrower bindings
  • safer storage decisions
  • faster incident response

The biggest win is clarity. Engineers stop asking whether they need an "access key" or a "gateway key" and start asking which workload identity they need the token to represent.

Key takeaways​

  • Keeptrusts uses one API-token system.
  • Token differences come from ABAC purpose, principal type, and bindings.
  • App-side gateway traffic usually maps to purpose=general.
  • Hosted gateway runtime identity usually maps to purpose=gateway_runtime.
  • Legacy labels are compatibility language only; the ABAC profile is the real source of meaning.

Next steps​