Skip to main content
TrueFoundry API keys are bearer tokens that let you authenticate to the platform programmatically — from the CLI / Python SDK, the REST API, the AI Gateway, the MCP Gateway, and CI/CD pipelines. The same token works across all of these surfaces.
The CLI and Python SDK accept the API key via the TFY_API_KEY environment variable. For HTTP APIs (REST, AI Gateway, MCP Gateway), pass the same token in the Authorization: Bearer … header.

​
Token types

TrueFoundry has two token types — pick the one that matches the identity you need:

​
Choosing between PAT and VAT

Avoid using PATs in production. If the user who created the PAT is deactivated or leaves the organization, the token stops working and your application will lose access.

​
Personal Access Tokens (PATs)

A PAT is created by a user and inherits all permissions of that user. Any user can create a PAT for themselves — admins can additionally configure tenant-wide limits and revoke other users’ tokens.

​
Create a PAT

In the platform, go to Access > Personal Access Tokens and create a new token. You can optionally assign a Team to the token so that all costs incurred through this token are attributed to the selected team.
Generate Personal Access Token form showing Name, Expiration Date, and Team fields

PAT creation form with optional team selection

Selecting a team on a PAT is for cost attribution only — it does not restrict the token’s permissions. The PAT still inherits the full permissions of the user who created it.
Save the token value when it’s first displayed — TrueFoundry will not show it again. Treat it like a password.

​
Admin controls

Admins can limit the maximum age and number of tokens that a single user can create under Settings > Security.
Security settings showing PAT age and count limits
Admins can require users to select a team when creating a PAT by enabling Mandate Team Selection in Personal Access Token (PAT) under Settings > Security. When enabled, every PAT must be associated with a team, ensuring that all API usage costs are attributed to a specific team. This is useful for organizations that need strict per-team cost tracking, especially when users belong to multiple teams.
Mandate Team Selection in Personal Access Token setting under Security configuration

Security setting to mandate team selection for PATs

Admins can revoke all active personal access tokens for a particular user from Access > Users.
Revoke all PATs option on a user account

​
Virtual Account tokens (VATs)

A virtual account is a non-user identity owned by an admin (or by a team if allowed by a custom role). It’s granted exactly the permissions an application needs, and its token survives staff turnover.
Use a separate virtual account per application or service. This gives you per-application usage tracking, independent rotation, and least-privilege scoping.
1

Create a virtual account

In the platform, go to Access > Virtual Accounts and create a new account, picking the resources and roles your application needs.
2

Get the token

Click Get Token on the virtual account to retrieve the bearer token. Use this as your API key in the application.Get Token button on a virtual account
3

(Optional) Configure rotation, notifications, or secret store sync

Virtual accounts support advanced lifecycle features that PATs don’t:
For full virtual account management — collaborators, permissions, deletion, and the management API — see Manage Virtual Accounts.

​
Using your API key

Pass your API key as a Bearer token in the Authorization header for all TrueFoundry HTTP APIs — REST, AI Gateway, and MCP Gateway:

​
Security best practices

  • Scope to least privilege. Grant a virtual account only the resources and roles its application needs — never reuse an admin’s token for a service.
  • Rotate regularly. Configure auto-rotation for VATs. For PATs, set tenant-wide age and count limits under Settings > Security.
  • Sync to a secret store. Use secret store sync so the live token lives in your secret manager rather than in source code or CI variables.
  • Revoke on suspicion. Admins can revoke all PATs for a user from Access > Users, and rotate or delete a virtual account from Access > Virtual Accounts.
  • Never commit tokens to source control. Read them from environment variables or your secret store at runtime.