openapi: 3.0.3
info:
  title: Alloy Automation Connectivity API
  description: >-
    The Alloy Connectivity API enables companies to build native integration UIs
    with a single API endpoint. Manage users, discover connector resources, configure
    credentials, and execute connector actions across 1000+ third-party applications.
  version: 2025-09
  contact:
    name: Alloy Automation Support
    url: https://runalloy.com/
  x-generated-from: documentation
servers:
  - url: https://production.runalloy.com
    description: Alloy Connectivity API production server
security:
  - ApiKey: []
tags:
  - name: Users
    description: User management for credential and connector access
  - name: Connectors
    description: Connector discovery and metadata operations
  - name: Credentials
    description: Connector credential management operations
  - name: Actions
    description: Connector action execution operations
paths:
  /users:
    post:
      operationId: createUser
      summary: Alloy Create User
      description: Create a user record in Alloy before managing credentials and executing connector actions.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              CreateUserRequestExample:
                summary: Default createUser request
                x-microcks-default: true
                value:
                  username: "user-123"
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                CreateUser201Example:
                  summary: Default createUser 201 response
                  x-microcks-default: true
                  value:
                    userId: "usr_abc123"
                    username: "user-123"
                    createdAt: "2026-04-19T10:00:00Z"
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /users/{userId}/token:
    get:
      operationId: generateUserToken
      summary: Alloy Generate User Token
      description: Generate a short-lived JWT for an end user to authenticate Alloy frontend SDK operations.
      tags:
        - Users
      parameters:
        - name: userId
          in: path
          required: true
          description: The unique identifier of the user
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: Token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
              examples:
                GenerateToken200Example:
                  summary: Default generateUserToken 200 response
                  x-microcks-default: true
                  value:
                    token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors:
    get:
      operationId: listConnectors
      summary: Alloy List Connectors
      description: Retrieve available connectors with metadata including icons, categories, and supported actions.
      tags:
        - Connectors
      parameters:
        - name: category
          in: query
          required: false
          description: Filter connectors by category
          schema:
            type: string
          example: "E-Commerce"
      responses:
        '200':
          description: Connectors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorList'
              examples:
                ListConnectors200Example:
                  summary: Default listConnectors 200 response
                  x-microcks-default: true
                  value:
                    connectors:
                      - connectorId: "shopify"
                        name: "Shopify"
                        category: "E-Commerce"
                        iconUrl: "https://assets.runalloy.com/icons/shopify.png"
                        actionCount: 45
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors/{connectorId}/resources:
    get:
      operationId: listConnectorResources
      summary: Alloy List Connector Resources
      description: List resources for a connector to discover the available entities and their supported actions.
      tags:
        - Connectors
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
      responses:
        '200':
          description: Connector resources retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceList'
              examples:
                ListConnectorResources200Example:
                  summary: Default listConnectorResources 200 response
                  x-microcks-default: true
                  value:
                    resources:
                      - resourceId: "orders"
                        name: "Orders"
                        description: "Shopify order management"
                        actions:
                          - "list"
                          - "get"
                          - "create"
        '404':
          description: Connector not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors/{connectorId}/actions/{actionId}:
    get:
      operationId: getConnectorAction
      summary: Alloy Get Connector Action
      description: Fetch action schema, parameters, and sample responses to configure a connector action call.
      tags:
        - Actions
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
        - name: actionId
          in: path
          required: true
          description: Unique identifier of the action
          schema:
            type: string
          example: "list-orders"
      responses:
        '200':
          description: Action details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorAction'
              examples:
                GetConnectorAction200Example:
                  summary: Default getConnectorAction 200 response
                  x-microcks-default: true
                  value:
                    actionId: "list-orders"
                    name: "List Orders"
                    description: "Retrieve a list of Shopify orders"
                    parameters:
                      - name: limit
                        type: integer
                        required: false
                        description: Maximum number of orders to return
        '404':
          description: Action not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors/{connectorId}/actions/{actionId}/execute:
    post:
      operationId: executeConnectorAction
      summary: Alloy Execute Connector Action
      description: Execute a connector action with specified parameters and user credentials.
      tags:
        - Actions
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
        - name: actionId
          in: path
          required: true
          description: Unique identifier of the action to execute
          schema:
            type: string
          example: "list-orders"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExecuteActionRequest'
            examples:
              ExecuteActionRequestExample:
                summary: Default executeConnectorAction request
                x-microcks-default: true
                value:
                  userId: "usr_abc123"
                  credentialId: "cred_xyz789"
                  parameters:
                    limit: 10
      responses:
        '200':
          description: Action executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResult'
              examples:
                ExecuteConnectorAction200Example:
                  summary: Default executeConnectorAction 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data:
                      orders:
                        - id: "order_001"
                          total: 99.99
        '400':
          description: Invalid request or action parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors/{connectorId}/credentials/metadata:
    get:
      operationId: getCredentialMetadata
      summary: Alloy Get Credential Metadata
      description: Check authentication requirements before creating credentials for a connector.
      tags:
        - Credentials
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
      responses:
        '200':
          description: Credential metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialMetadata'
              examples:
                GetCredentialMetadata200Example:
                  summary: Default getCredentialMetadata 200 response
                  x-microcks-default: true
                  value:
                    connectorId: "shopify"
                    authType: "oauth2"
                    requiredFields:
                      - name: "shop_domain"
                        description: "Your Shopify store domain"
                        required: true
        '404':
          description: Connector not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /connectors/{connectorId}/credentials:
    post:
      operationId: createCredential
      summary: Alloy Create Credential
      description: Create a credential for a user for a specific connector to enable authenticated action execution.
      tags:
        - Credentials
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCredentialRequest'
            examples:
              CreateCredentialRequestExample:
                summary: Default createCredential request
                x-microcks-default: true
                value:
                  userId: "usr_abc123"
                  data:
                    shop_domain: "mystore.myshopify.com"
      responses:
        '201':
          description: Credential created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
              examples:
                CreateCredential201Example:
                  summary: Default createCredential 201 response
                  x-microcks-default: true
                  value:
                    credentialId: "cred_xyz789"
                    connectorId: "shopify"
                    userId: "usr_abc123"
                    createdAt: "2026-04-19T10:00:00Z"
        '400':
          description: Invalid credential data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

    get:
      operationId: listCredentials
      summary: Alloy List Credentials
      description: List existing credentials for a user on a specific connector.
      tags:
        - Credentials
      parameters:
        - name: connectorId
          in: path
          required: true
          description: Unique identifier of the connector
          schema:
            type: string
          example: "shopify"
        - name: userId
          in: query
          required: true
          description: Filter credentials by user identifier
          schema:
            type: string
          example: "usr_abc123"
      responses:
        '200':
          description: Credentials retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialList'
              examples:
                ListCredentials200Example:
                  summary: Default listCredentials 200 response
                  x-microcks-default: true
                  value:
                    credentials:
                      - credentialId: "cred_xyz789"
                        connectorId: "shopify"
                        userId: "usr_abc123"
                        createdAt: "2026-04-19T10:00:00Z"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: API key in Authorization header (bearer YOUR_API_KEY)

  schemas:
    User:
      title: User
      type: object
      description: A user in the Alloy Connectivity platform
      properties:
        userId:
          type: string
          description: Unique identifier for the user
          example: "usr_abc123"
        username:
          type: string
          description: Username or external identifier
          example: "user-123"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the user was created
          example: "2026-04-19T10:00:00Z"

    CreateUserRequest:
      title: CreateUserRequest
      type: object
      description: Request body for creating a new user
      required:
        - username
      properties:
        username:
          type: string
          description: Unique username or external identifier
          example: "user-123"

    TokenResponse:
      title: TokenResponse
      type: object
      description: JWT token response
      properties:
        token:
          type: string
          description: Short-lived JSON Web Token
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"

    Connector:
      title: Connector
      type: object
      description: A third-party application connector available in Alloy
      properties:
        connectorId:
          type: string
          description: Unique identifier for the connector
          example: "shopify"
        name:
          type: string
          description: Display name of the connector
          example: "Shopify"
        category:
          type: string
          description: Connector category
          example: "E-Commerce"
        iconUrl:
          type: string
          format: uri
          description: URL to the connector icon
          example: "https://assets.runalloy.com/icons/shopify.png"
        actionCount:
          type: integer
          description: Number of available actions for this connector
          example: 45

    ConnectorList:
      title: ConnectorList
      type: object
      description: List of available connectors
      properties:
        connectors:
          type: array
          description: List of connector records
          items:
            $ref: '#/components/schemas/Connector'

    Resource:
      title: Resource
      type: object
      description: A resource entity available in a connector
      properties:
        resourceId:
          type: string
          description: Unique identifier for the resource
          example: "orders"
        name:
          type: string
          description: Display name of the resource
          example: "Orders"
        description:
          type: string
          description: Description of the resource
          example: "Shopify order management"
        actions:
          type: array
          description: List of supported action names for this resource
          items:
            type: string
          example:
            - "list"
            - "get"
            - "create"

    ResourceList:
      title: ResourceList
      type: object
      description: List of resources for a connector
      properties:
        resources:
          type: array
          description: List of resource records
          items:
            $ref: '#/components/schemas/Resource'

    ConnectorAction:
      title: ConnectorAction
      type: object
      description: A specific action available for a connector
      properties:
        actionId:
          type: string
          description: Unique identifier for the action
          example: "list-orders"
        name:
          type: string
          description: Display name of the action
          example: "List Orders"
        description:
          type: string
          description: Description of what the action does
          example: "Retrieve a list of Shopify orders"
        parameters:
          type: array
          description: Parameters accepted by this action
          items:
            $ref: '#/components/schemas/ActionParameter'

    ActionParameter:
      title: ActionParameter
      type: object
      description: A parameter definition for a connector action
      properties:
        name:
          type: string
          description: Parameter name
          example: "limit"
        type:
          type: string
          description: Parameter data type
          example: "integer"
        required:
          type: boolean
          description: Whether the parameter is required
          example: false
        description:
          type: string
          description: Description of the parameter
          example: "Maximum number of orders to return"

    ExecuteActionRequest:
      title: ExecuteActionRequest
      type: object
      description: Request body for executing a connector action
      required:
        - userId
        - credentialId
      properties:
        userId:
          type: string
          description: Identifier of the user executing the action
          example: "usr_abc123"
        credentialId:
          type: string
          description: Credential identifier to use for authentication
          example: "cred_xyz789"
        parameters:
          type: object
          description: Action-specific parameters
          example:
            limit: 10

    ActionResult:
      title: ActionResult
      type: object
      description: Result of a connector action execution
      properties:
        success:
          type: boolean
          description: Whether the action executed successfully
          example: true
        data:
          type: object
          description: Action result data
          example:
            orders:
              - id: "order_001"
                total: 99.99

    CredentialMetadata:
      title: CredentialMetadata
      type: object
      description: Authentication requirements for a connector
      properties:
        connectorId:
          type: string
          description: Connector identifier
          example: "shopify"
        authType:
          type: string
          description: Authentication type required
          enum:
            - oauth2
            - api_key
            - basic
          example: "oauth2"
        requiredFields:
          type: array
          description: Fields required to create credentials
          items:
            $ref: '#/components/schemas/CredentialField'

    CredentialField:
      title: CredentialField
      type: object
      description: A required field for credential creation
      properties:
        name:
          type: string
          description: Field name
          example: "shop_domain"
        description:
          type: string
          description: Field description
          example: "Your Shopify store domain"
        required:
          type: boolean
          description: Whether this field is required
          example: true

    Credential:
      title: Credential
      type: object
      description: A stored credential for a user's connector
      properties:
        credentialId:
          type: string
          description: Unique identifier for the credential
          example: "cred_xyz789"
        connectorId:
          type: string
          description: Connector this credential belongs to
          example: "shopify"
        userId:
          type: string
          description: User this credential belongs to
          example: "usr_abc123"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the credential was created
          example: "2026-04-19T10:00:00Z"

    CreateCredentialRequest:
      title: CreateCredentialRequest
      type: object
      description: Request body for creating a connector credential
      required:
        - userId
        - data
      properties:
        userId:
          type: string
          description: Identifier of the user
          example: "usr_abc123"
        data:
          type: object
          description: Connector-specific credential data
          example:
            shop_domain: "mystore.myshopify.com"

    CredentialList:
      title: CredentialList
      type: object
      description: List of credentials for a user on a connector
      properties:
        credentials:
          type: array
          description: List of credential records
          items:
            $ref: '#/components/schemas/Credential'

    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Standard error response
      properties:
        error:
          type: string
          description: Error code or type
          example: "UNAUTHORIZED"
        message:
          type: string
          description: Human-readable error description
          example: "Invalid API key"