openapi: 3.1.0
info:
  title: Upvest Investment Account Transfers Authentication API
  description: The Upvest Investment API provides a unified interface for building embedded investment experiences. It supports placing and managing orders, creating portfolios, configuring savings plans, handling securities transfers, and managing user accounts and positions. The API covers the full order lifecycle with asynchronous processing and webhook notifications for real-time event handling. Financial institutions can use the API to offer fractional investing, automated portfolio management, and localized investment products across European and UK markets.
  version: 1.0.0
  contact:
    name: Upvest Support
    url: https://upvest.co/
  termsOfService: https://upvest.co/legal
servers:
- url: https://api.upvest.co
  description: Production Server
- url: https://sandbox.upvest.co
  description: Sandbox Server
security:
- oauth2ClientCredentials: []
tags:
- name: Authentication
  description: OAuth 2.0 token management for API access using client credentials flow.
paths:
  /auth/token:
    post:
      operationId: createAccessToken
      summary: Upvest Create an access token
      description: Obtain an OAuth 2.0 access token using client credentials. The returned opaque access token is used to authenticate subsequent API requests. You must specify the required scopes for the endpoints you intend to call.
      tags:
      - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - grant_type
              - client_id
              - client_secret
              - scope
              properties:
                grant_type:
                  type: string
                  enum:
                  - client_credentials
                  description: The OAuth 2.0 grant type. Must be client_credentials.
                client_id:
                  type: string
                  description: The client identifier issued during onboarding.
                client_secret:
                  type: string
                  description: The client secret issued during onboarding.
                scope:
                  type: string
                  description: A space-separated list of scopes to request.
      responses:
        '200':
          description: Access token successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
              examples:
                createAccessToken200Example:
                  summary: Default createAccessToken 200 response
                  x-microcks-default: true
                  value:
                    access_token: eyJhbGciOiJSUzI1NiJ9.example
                    token_type: bearer
                    expires_in: 3600
                    scope: users:read accounts:read
        '401':
          description: Invalid client credentials or missing scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                createAccessToken401Example:
                  summary: Default createAccessToken 401 response
                  x-microcks-default: true
                  value:
                    type: standard
                    status: 100
                    title: example-value
                    detail: example-value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Error:
      type: object
      description: An API error response.
      properties:
        type:
          type: string
          description: The error type identifier.
          example: standard
        status:
          type: integer
          description: The HTTP status code.
          example: 100
        title:
          type: string
          description: A short human-readable summary of the error.
          example: example-value
        detail:
          type: string
          description: A detailed human-readable explanation of the error.
          example: example-value
    AccessToken:
      type: object
      description: An OAuth 2.0 access token for authenticating API requests.
      properties:
        access_token:
          type: string
          description: The opaque access token string.
          example: eyJhbGciOiJSUzI1NiJ9.example
        token_type:
          type: string
          enum:
          - bearer
          description: The type of token issued.
          example: bearer
        expires_in:
          type: integer
          description: The lifetime of the access token in seconds.
          example: 3600
        scope:
          type: string
          description: The scopes granted to the access token.
          example: users:read accounts:read
  securitySchemes:
    oauth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 client credentials flow. Obtain an access token by providing your client ID and client secret.
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes:
            users:read: Read user data
            users:admin: Onboard and manage users
            accounts:read: Read account data
            accounts:admin: Create and manage accounts
            orders:read: Read order data
            orders:admin: Place and manage orders
            instruments:read: Read instrument data
            portfolios:read: Read portfolio data
            portfolios:admin: Create and manage portfolios
            positions:read: Read position data
            payments:read: Read payment data
            payments:admin: Manage payments and direct debits
            reports:read: Read reports
            webhooks:read: Read webhook subscriptions
            webhooks:admin: Manage webhook subscriptions
            transactions:read: Read transaction data
            fees:read: Read fee data
            fees:admin: Configure fees
externalDocs:
  description: Upvest API Documentation
  url: https://docs.upvest.co/