Vertesia Token Service API

openapi: 3.2.0
info:
  title: Vertesia Token Service API
  version: 1.6.0-dev.20261019.172735Z
  x-api-version: '20260803'
  description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
  contact:
    name: Vertesia
    url: https://vertesiahq.com/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-scalar-sdk-installation:
  - lang: Node
    description: 'Install the **Vertesia Client** from npm:'
    source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
  description: Vertesia API
  variables:
    region:
      default: us1
      enum:
      - us1
      - eu1
      - jp1
      description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Token Service
  description: Security Token Service endpoints issue short-lived project, user, environment, service-account, and agent tokens.
paths:
  /token/app-session:
    post:
      operationId: MintAppSessionToken
      tags:
      - Token Service
      summary: Mint a scoped iframe app session
      security:
      - bearerAuth: []
      - OAuth2: []
      parameters: []
      responses:
        '200':
          description: A short-lived app-scoped token without a refresh token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppSessionTokenResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/token-server/src/api/token.ts
        className: TokensResource
        methodName: appSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppSessionTokenRequest'
      servers:
      - url: https://sts.{region}.vertesia.io
        description: Vertesia STS
        variables:
          region:
            default: us1
            enum:
            - us1
            - eu1
            - jp1
            description: Regional STS host label. `us1` is the global endpoint.
  /token/issue:
    post:
      operationId: IssueToken
      tags:
      - Token Service
      summary: Issue a token
      description: Issues a short-lived Vertesia token from workload credentials. For API key authentication, the request body is optional and the API key in the Authorization header is used as the token source.
      security:
      - bearerAuth: []
      parameters: []
      responses:
        '200':
          description: The issued token and expiry metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTokenResponse'
        '403':
          description: The authenticated identity cannot use the requested scope or environment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTokenForbiddenResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Internal Server Error
                status: 500
                message: Internal server error.
        '503':
          description: Token signing is temporarily unavailable. Retryable; honor the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTokenUnavailableResponse'
        4XX:
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Bad Request
                status: 400
                message: Request validation failed.
      x-vertesia-permissions: []
      x-vertesia-source:
        file: ../../apps/token-server/src/api/token.ts
        className: TokensResource
        methodName: issueToken
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueTokenRequest'
      servers:
      - url: https://sts.{region}.vertesia.io
        description: Vertesia STS
        variables:
          region:
            default: us1
            enum:
            - us1
            - eu1
            - jp1
            description: Regional STS host label. `us1` is the global endpoint.
components:
  schemas:
    EnvironmentTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: environment
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        environment_id:
          type: string
        environment_name:
          type: string
        project_id:
          type: string
        account_id:
          type: string
      required:
      - account_id
      - environment_id
      - environment_name
      - project_id
      - type
      additionalProperties: false
    ApiKeyTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: apikey
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        key:
          type: string
      required:
      - key
      - type
      additionalProperties: false
    IssueTokenResponse:
      type: object
      properties:
        token:
          type: string
        token_type:
          type: string
          const: Bearer
        expires_in:
          type: number
      required:
      - token
      - token_type
      additionalProperties: false
    AppSessionTokenResponse:
      type: object
      properties:
        token:
          type: string
        token_type:
          type: string
          const: Bearer
        expires_in:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
      - token
      - token_type
      - expires_in
      additionalProperties: false
    IssueTokenUnavailableResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
      - error
      - message
      additionalProperties: false
    ServiceAccountTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: service_account
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        account_id:
          type: string
        project_id:
          type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/SystemRoles'
        name:
          type: string
        email:
          type: string
      required:
      - account_id
      - project_id
      - type
      additionalProperties: false
    SystemRoles:
      type: string
      enum:
      - owner
      - admin
      - app_admin
      - manager
      - developer
      - application
      - automation
      - content_processor
      - consumer
      - executor
      - reader
      - auditor
      - support
      - billing
      - member
      - app_member
      - content_superadmin
    IssueTokenRequest:
      oneOf:
      - $ref: '#/components/schemas/ApiKeyTokenRequest'
      - $ref: '#/components/schemas/UserTokenRequest'
      - $ref: '#/components/schemas/ProjectTokenRequest'
      - $ref: '#/components/schemas/EnvironmentTokenRequest'
      - $ref: '#/components/schemas/AgentTokenRequest'
      - $ref: '#/components/schemas/ServiceAccountTokenRequest'
      discriminator:
        propertyName: type
        mapping:
          apikey: '#/components/schemas/ApiKeyTokenRequest'
          user: '#/components/schemas/UserTokenRequest'
          project: '#/components/schemas/ProjectTokenRequest'
          environment: '#/components/schemas/EnvironmentTokenRequest'
          agent: '#/components/schemas/AgentTokenRequest'
          service_account: '#/components/schemas/ServiceAccountTokenRequest'
      type: object
      required:
      - type
    AppSessionTokenRequest:
      type: object
      properties:
        app_name:
          type: string
          minLength: 1
        scopes:
          type: array
          items:
            type: string
        ttl_seconds:
          type: integer
          minimum: 1
          maximum: 900
      required:
      - app_name
      additionalProperties: false
    IssueTokenForbiddenResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        errorCode:
          type: string
          enum:
          - requested_scope_unavailable
          - no_accessible_account
          - restricted_environment
          - token_issuance_forbidden
      required:
      - error
      - message
      - errorCode
      additionalProperties: false
      description: A safe, machine-readable denial response. Requested resources are intentionally not identified or confirmed.
    ProjectTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: project
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        project_id:
          type: string
        account_id:
          type: string
      required:
      - account_id
      - project_id
      - type
      additionalProperties: false
    AgentTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: agent
        delegation_grant_id:
          type: string
        delegation_policy_hash:
          type: string
        continuation_token:
          type: string
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        account_id:
          type: string
        project_id:
          type: string
        name:
          type: string
        on_behalf_of:
          type: string
          description: 'User information.


            The value of this field can be either:   - a signed Vertesia token used to verify the user context   - a user ID prefixed with `user:` to indicate the user on behalf of whom the agent is     acting.'
      required:
      - account_id
      - on_behalf_of
      - project_id
      - type
      additionalProperties: false
      description: 'Agent token for a service account to act as agent on behalf of a user.


        Two trust paths are supported:


        - `user_access_token`: a live signed Vertesia token. STS verifies the user context from that token.

        - `workload_id_token`: a workload acts on behalf of a user. It implies that a full verification   will be performed based on the workload identity.'
    SigningAlgorithm:
      type: string
      enum:
      - ES256
      - RS256
    ErrorResponse:
      type: object
      description: Standard JSON error response returned by the server error handler.
      properties:
        error:
          type: string
          description: HTTP status text or normalized error type.
        status:
          type: integer
          format: int32
          minimum: 400
          maximum: 599
          description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
          example: 400
        message:
          type: string
          description: Human-readable error message.
        details:
          type: string
          description: Optional additional error details.
        errorCode:
          type: string
          description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
          example: account_api_key_creation_disabled
      required:
      - error
      - status
      additionalProperties: false
    UserTokenRequest:
      type: object
      properties:
        type:
          type: string
          const: user
        audience:
          type: string
        algorithm:
          $ref: '#/components/schemas/SigningAlgorithm'
          description: Signing algorithm - defaults to ES256. Use RS256 for Azure AD compatibility.
        user_id:
          type: string
        account_id:
          type: string
        project_id:
          type: string
        expires_at:
          type: number
        on_behalf_of:
          type: string
      required:
      - type
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
          tokenUrl: https://sts.vertesia.io/oauth/token
          x-scalar-security-query:
            resource: https://api.us1.vertesia.io/api/v1
          x-scalar-security-body:
            resource: https://api.us1.vertesia.io/api/v1
          scopes:
            openid: ''
            profile: ''
            offline_access: ''
            interaction:read: ''
            interaction:write: ''
            interaction:delete: ''
            interaction:execute: ''
            run:read: ''
            run:write: ''
            environment:admin: ''
            app:manage: ''
            project:admin: ''
            project:integration_read: ''
            project:settings_write: ''
            api_key:read: ''
            account:read: ''
            account:write: ''
            account:admin: ''
            audit:read: ''
            account:member: ''
            content:read: ''
            content:read_all: ''
            content:write: ''
            content:delete: ''
            content:admin: ''
            content:superadmin: ''
            workflow:read: ''
            workflow:run: ''
            workflow:admin: ''
            workflow:superadmin: ''
            agent_run:read: ''
            task:read: ''
            task:manage: ''
x-tagGroups:
- name: Authentication
  tags:
  - Token Service
- name: GenAI
  tags:
  - Environments
  - Prompt Templates
  - Interactions
  - Interaction Runs
  - Agent Runs
- name: Content
  tags:
  - Content Object Types
  - Objects
  - Collections
  - Files
  - Rendering
  - Bulk Operations
  - Commands
- name: Data Store
  tags:
  - Data
- name: Workflow
  tags:
  - Processes
  - Tasks
  - Workflow Definitions
  - Workflow Rules
  - Workflow Runs
- name: Administration
  tags:
  - Accounts
  - Projects
  - Audit Trail
  - Costs
- name: Access Control
  tags:
  - Users
  - User Groups
  - Roles
  - Access Control Entries
  - API Keys
- name: Apps & Integrations
  tags:
  - Apps
  - OAuth Providers
  - OAuth Clients
  - OAuth Grants
  - Remote MCP Connections