> ## Documentation Index > Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a virtual account > Create a new virtual account or update an existing one using the provided VirtualAccountManifest. Matching is by name — if the name matches an existing virtual account it is updated, otherwise a new one is created. ## OpenAPI ````yaml /openapi.json put /api/svc/v1/virtual-accounts openapi: 3.1.0 info: title: TrueFoundry API description: API for TrueFoundry version: 0.1.0 contact: {} servers: - url: https://{controlPlaneURL} variables: controlPlaneURL: default: app.truefoundry.com description: Control Plane URL security: [] tags: - name: Agent - name: Agent Skills - name: Applications - name: Metrics - name: Apply - name: Artifacts - name: Audit Logs - name: Clusters - name: Jobs - name: Logs - name: MCP Servers V2 - name: MLRepos - name: Model Deployments - name: Models - name: Personal Access Tokens - name: Prompts - name: Provider Integrations - name: SCIM v2 - name: Secret Groups - name: Secrets - name: Teams - name: Traces - name: Users - name: Virtual Accounts - name: Role Bindings - name: Workspaces paths: /api/svc/v1/virtual-accounts: put: tags: - Virtual Accounts summary: Create or update a virtual account description: >- Create a new virtual account or update an existing one using the provided VirtualAccountManifest. Matching is by name — if the name matches an existing virtual account it is updated, otherwise a new one is created. operationId: VirtualAccount.createOrUpdateVirtualAccount parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ApplyVirtualAccountRequest' responses: '200': description: The created or updated virtual account. content: application/json: schema: $ref: '#/components/schemas/GetVirtualAccountResponse' '400': description: >- Bad Request — manifest validation failed, invalid name, or tenant permission validation errors. content: application/json: schema: $ref: '#/components/schemas/HttpError' '422': description: >- Unprocessable Entity — virtual account must have at least one permission, expiration date cannot be changed on update, invalid date format, or expiration date is in the past. content: application/json: schema: $ref: '#/components/schemas/HttpError' security: - jwt: [] components: schemas: ApplyVirtualAccountRequest: type: object properties: manifest: oneOf: - $ref: '#/components/schemas/VirtualAccountManifest' description: >- The virtual account manifest describing the virtual account to create or update. dryRun: type: boolean default: false description: When true, validate the request without persisting any changes. nullable: true required: - manifest title: ApplyVirtualAccountRequest x-fern-type-name: ApplyVirtualAccountRequest GetVirtualAccountResponse: type: object properties: data: description: The requested virtual account. allOf: - $ref: '#/components/schemas/VirtualAccount' token: type: string description: >- Authentication token for the virtual account. Present only on creation. nullable: true required: - data title: GetVirtualAccountResponse x-fern-type-name: GetVirtualAccountResponse HttpError: type: object properties: statusCode: type: integer description: HTTP Status Code message: type: string description: Error Message code: oneOf: - type: integer - type: string description: Error code nullable: true details: type: array description: Error details items: type: object nullable: true required: - statusCode - message title: HttpError x-fern-type-name: HttpError VirtualAccountManifest: type: object required: - name - type - permissions properties: name: description: Virtual Account Name type: string pattern: ^[a-z][a-z0-9\-]{1,34}[a-z0-9]$ type: description: +value=virtual-account type: string enum: - virtual-account permissions: description: Permissions type: array items: $ref: '#/components/schemas/Permissions' expiration_date: description: >- Expiration Date of the Virtual Account (should be in the format yyyy-mm-dd) type: string pattern: ^\d{4}-\d{2}-\d{2}$ auto_rotate: $ref: '#/components/schemas/AutoRotate' notification_target: $ref: '#/components/schemas/NotificationTarget' secret_store_config: $ref: '#/components/schemas/SecretStoreConfig' ownedBy: $ref: '#/components/schemas/VirtualAccountOwnedBy' tags: description: >- Key-value pairs to categorize this Virtual Account (e.g., by owner or environment). type: object identity_provider_mapping: description: >- Mappings from external identity provider claim value to this virtual account type: array items: $ref: '#/components/schemas/IdentityProviderMapping' token_type: description: Format of the issued token. Leave empty to use the platform default. type: string enum: - jwt - opaque title: VirtualAccountManifest x-fern-type-name: VirtualAccountManifest VirtualAccount: type: object properties: id: type: string description: System-generated virtual account ID. example: jqfwg345gi25n5ju2yz5iz6m type: type: string description: Type of service account. tenantName: type: string description: Tenant the virtual account belongs to. manifest: oneOf: - $ref: '#/components/schemas/VirtualAccountManifest' - $ref: '#/components/schemas/PersonalAccessTokenManifest' nullable: true description: >- The manifest defining name, permissions, ownership, and configuration. jwtId: type: string nullable: true description: System-generated ID of the currently active JWT. createdBySubject: description: >- The subject (user or service account) that created this virtual account. allOf: - $ref: '#/components/schemas/Subject' createdAt: format: date-time type: string description: Timestamp when the virtual account was created. updatedAt: format: date-time type: string description: Timestamp when the virtual account was last updated. lastAccessedAt: format: date-time type: string nullable: true description: Timestamp when the virtual account was last used to authenticate. isExpired: type: boolean nullable: true description: Whether the virtual account token has expired. jwts: nullable: true description: JWT tokens associated with this virtual account. type: array items: $ref: '#/components/schemas/Jwt' accountId: type: string nullable: false description: ID of the account that owns this virtual account. metadata: type: object additionalProperties: true nullable: true description: Additional metadata for the virtual account. roleIds: nullable: true description: Role IDs assigned to this virtual account. type: array items: type: string rolesWithResource: nullable: true description: Roles with their associated resources. type: array items: $ref: '#/components/schemas/RoleWithResource' createdBy: type: string nullable: true nextScheduledRotation: type: string nullable: true required: - id - type - tenantName - createdBySubject - createdAt - updatedAt - accountId title: VirtualAccount x-fern-type-name: VirtualAccount Permissions: type: object required: - resource_fqn - resource_type - role_id properties: resource_fqn: description: The fully qualified name of the resource type: string resource_type: description: The type of the resource (cluster, workspace, etc.) type: string role_id: description: >- The role id of the role to be assigned to the service account for that resource type: string title: Permissions x-fern-type-name: Permissions AutoRotate: description: Enable Auto Rotation to automatically rotate the token type: object required: - auto_rotate_interval - grace_period properties: auto_rotate_interval: description: >- Rotation Interval in days after which the token will be rotated. Minimum value is 30. type: integer minimum: 30 default: 360 grace_period: description: >- Grace Period in days for which the token will be valid after rotation interval. Minimum value is 1. type: integer minimum: 1 default: 30 title: AutoRotate x-fern-type-name: AutoRotate NotificationTarget: description: +discriminator=type type: object oneOf: - $ref: '#/components/schemas/Email' - $ref: '#/components/schemas/SlackWebhook' - $ref: '#/components/schemas/SlackBot' - $ref: '#/components/schemas/PagerDuty' - $ref: '#/components/schemas/MSTeamsWebhook' discriminator: propertyName: type title: NotificationTarget x-fern-type-name: NotificationTarget SecretStoreConfig: description: Enable to store the virtual account token in a secret store type: object required: - integration_fqn - secret_path properties: integration_fqn: description: The secret store to store the virtual account token in type: string secret_path: description: >- The path where the virtual account token will be stored in the secret store (example: secret/path/to/virtual-account-token) type: string pattern: ^/?[A-Za-z0-9/-]*[A-Za-z0-9]$ title: SecretStoreConfig x-fern-type-name: SecretStoreConfig VirtualAccountOwnedBy: description: Names of the owners that own the virtual account type: object required: - team properties: account: description: The name of the account that owns this resource type: string team: description: The name of the team that owns this resource type: string title: VirtualAccountOwnedBy x-fern-type-name: VirtualAccountOwnedBy IdentityProviderMapping: description: Configuration for mapping IdP claim values to this virtual account type: object required: - identity_provider - value properties: identity_provider: description: Name of the external identity provider type: string value: description: Claim value that should resolve to this virtual account type: string title: IdentityProviderMapping x-fern-type-name: IdentityProviderMapping PersonalAccessTokenManifest: type: object required: - name - type - user_fqn properties: name: description: Personal Access Token Name type: string pattern: ^[a-z][a-z0-9\-]{1,34}[a-z0-9]$ type: description: +value=pat type: string enum: - pat expiration_date: description: >- Expiration Date of the Personal Access Token (should be in the ISO 8601 format) type: string pattern: ^\S+$ user_fqn: description: The fully qualified name of the user type: string ownedBy: $ref: '#/components/schemas/VirtualAccountOwnedBy' token_type: description: Format of the issued token. Leave empty to use the platform default. type: string enum: - jwt - opaque title: PersonalAccessTokenManifest x-fern-type-name: PersonalAccessTokenManifest Subject: type: object properties: subjectId: type: string description: Subject ID subjectType: description: Subject type allOf: - $ref: '#/components/schemas/SubjectType' subjectSlug: type: string description: Subject slug nullable: true subjectDisplayName: type: string description: Subject display name nullable: true subjectPatName: type: string description: Subject PAT name nullable: true subjectControllerName: type: string nullable: true subjectExternalIdentitySlug: type: string description: External identity slug (external_identity_id:sub:email) nullable: true required: - subjectId - subjectType title: Subject x-fern-type-name: Subject Jwt: type: object properties: id: type: string subjectType: type: string subjectId: type: string metadata: type: object additionalProperties: true nullable: true expiry: format: date-time type: string tokenType: type: string enum: - jwt - opaque createdAt: format: date-time type: string updatedAt: format: date-time type: string required: - id - subjectType - subjectId - expiry - tokenType - createdAt - updatedAt title: Jwt x-fern-type-name: Jwt RoleWithResource: type: object properties: roleId: type: string resourceType: type: string enum: - role - account - cluster - workspace - environment - secret-group - deployment - application - secret - docker-registry - tenant - vcs-integration - mlf-project - repository - provider-integration - team - service-account - llm-gateway - policy - role-binding - settings - provider-account - user - alert-config - alert-rule - gateway-config - gateway-controls - gateway-budget - tracing-project - tracing-application - agent - agent-app - gateway-installation - virtual-account - sso-based-identity - external-identity - mcp-server - external-identity-provider - agent-identity resourceId: type: string roleName: type: string required: - roleId - resourceType - resourceId - roleName title: RoleWithResource x-fern-type-name: RoleWithResource Email: description: Email type: object required: - type - notification_channel - to_emails properties: type: description: +value=email type: string enum: - email notification_channel: description: Specify the notification channel to send alerts to type: string minLength: 1 to_emails: description: >- List of recipients' email addresses if the notification channel is Email. type: array items: type: string minLength: 1 title: Email x-fern-type-name: Email SlackWebhook: description: Slack Webhook type: object required: - type - notification_channel properties: type: description: +value=slack-webhook type: string enum: - slack-webhook notification_channel: description: Specify the notification channel to send alerts to type: string minLength: 1 title: SlackWebhook x-fern-type-name: SlackWebhook SlackBot: type: object required: - type - notification_channel - channels properties: type: description: +value=slack-bot type: string enum: - slack-bot notification_channel: description: Specify the notification channel to send alerts to type: string minLength: 1 channels: description: List of channels to send messages to. type: array items: type: string pattern: ^#[a-z0-9\-_]{2,80}$ title: SlackBot x-fern-type-name: SlackBot PagerDuty: type: object required: - type - notification_channel properties: type: description: +value=pagerduty type: string enum: - pagerduty notification_channel: description: Specify the notification channel to send alerts to type: string minLength: 1 title: PagerDuty x-fern-type-name: PagerDuty MSTeamsWebhook: description: MS Teams Webhook type: object required: - type - notification_channel properties: type: description: +value=ms-teams-webhook type: string enum: - ms-teams-webhook notification_channel: description: Specify the notification channel to send alerts to type: string minLength: 1 title: MSTeamsWebhook x-fern-type-name: MSTeamsWebhook SubjectType: type: string enum: - user - team - serviceaccount - virtualaccount - external-identity - agent-identity - role description: >- Type of the authenticated subject. "user" for human users, "serviceaccount" (also known as virtual account) for programmatic access. title: SubjectType x-fern-type-name: SubjectType securitySchemes: jwt: type: http scheme: bearer bearerFormat: JWT ````