> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create tenant provider configuration

> Create a new DDEX provider configuration for the current tenant.

## Description

The `credentials` object structure depends on the `deliveryMethod`:

* **SFTP**: Use `SFTPCredentials` schema (host, port, username, password, remotePath)
* **FTP**: Use `SFTPCredentials` schema with port 21
* **HTTP/HTTPS**: Use `HTTPCredentials` schema (apiUrl, authType, bearerToken/apiKey)
* **AS2**: Use `AS2Credentials` schema (endpoint, as2From, as2To)
* **WebDAV**: Use `WebDAVCredentials` schema (url, username, password)

Credentials are encrypted at rest using PostgreSQL pgcrypto.

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.royalti.io/ddex/tenant-providers', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      "providerId": "sample-providerId",
      "labelId": "sample-labelId",
      "deliveryMethod": "sample-deliveryMethod",
      "customSettings": {},
      "priority": 1,
      "rateLimits": {},
      "acknowledgementSettings": {}
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
    'https://api.royalti.io/ddex/tenant-providers',
    json={"providerId":"sample-providerId","labelId":"sample-labelId","deliveryMethod":"sample-deliveryMethod","customSettings":{},"priority":1,"rateLimits":{},"acknowledgementSettings":{}}
  )

  data = response.json()
  print(data)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.royalti.io/ddex/tenant-providers \
    -H "Content-Type: application/json" \
    -d '{"providerId":"sample-providerId","labelId":"sample-labelId","deliveryMethod":"sample-deliveryMethod","customSettings":{},"priority":1,"rateLimits":{},"acknowledgementSettings":{}}'

  ```
</CodeGroup>


## OpenAPI

````yaml post /ddex/tenant-providers
openapi: 3.0.0
info:
  title: Royalti.io API
  description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
  version: 2.6.0
  contact:
    name: Royalti.io Support
    email: support@royalti.io
    url: https://royalti.io
  license:
    name: Proprietary
    url: https://royalti.io/terms
servers:
  - url: https://api.royalti.io
    description: Production server
  - url: https://api-dev.royalti.io
    description: Development server
  - url: http://localhost:8084
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Accounting
    description: Accounting and financial transaction operations
  - name: DDEX
    description: DDEX operations (ERN/MEAD, messages, delivery, providers)
  - name: Label
    description: Label management operations
  - name: Internal Webhooks
    description: Internal system webhooks for royalty processing and downloads
  - name: Payment Webhooks
    description: Payment processor webhook endpoints
  - name: Billing Webhooks
    description: Stripe billing and subscription webhooks
  - name: Infrastructure Webhooks
    description: Cloudflare domain and SSL webhooks
  - name: Distribution Webhooks
    description: Digital distribution platform webhooks (FUGA)
paths:
  /ddex/tenant-providers:
    post:
      tags:
        - DDEX
      summary: Create tenant provider configuration
      description: >-
        Create a new DDEX provider configuration for the current tenant.


        The `credentials` object structure depends on the `deliveryMethod`:

        - **SFTP**: Use `SFTPCredentials` schema (host, port, username,
        password, remotePath)

        - **FTP**: Use `SFTPCredentials` schema with port 21

        - **HTTP/HTTPS**: Use `HTTPCredentials` schema (apiUrl, authType,
        bearerToken/apiKey)

        - **AS2**: Use `AS2Credentials` schema (endpoint, as2From, as2To)

        - **WebDAV**: Use `WebDAVCredentials` schema (url, username, password)


        Credentials are encrypted at rest using PostgreSQL pgcrypto.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - providerId
                - deliveryMethod
                - credentials
              properties:
                providerId:
                  type: string
                  format: uuid
                  description: ID of the DDEX provider from the provider catalog
                labelId:
                  type: string
                  format: uuid
                  nullable: true
                  description: Optional label ID for label-specific configuration
                deliveryMethod:
                  type: string
                  enum:
                    - SFTP
                    - FTP
                    - HTTP
                    - HTTPS
                    - AS2
                    - WebDAV
                  description: Delivery protocol to use
                credentials:
                  $ref: '#/components/schemas/ProviderCredentials'
                customSettings:
                  type: object
                  description: Provider-specific custom settings
                priority:
                  type: integer
                  description: Priority for this provider (higher = preferred)
                  default: 50
                rateLimits:
                  type: object
                  description: Rate limiting configuration
                acknowledgementSettings:
                  type: object
                  description: MDN/acknowledgement settings
            examples:
              sftp:
                summary: SFTP Configuration
                value:
                  providerId: 123e4567-e89b-12d3-a456-426614174000
                  deliveryMethod: SFTP
                  credentials:
                    host: ftp.provider.com
                    port: 22
                    username: myuser
                    password: mypassword
                    remotePath: /incoming/ddex
                    secure: true
                  priority: 50
              http:
                summary: HTTP API Configuration
                value:
                  providerId: 123e4567-e89b-12d3-a456-426614174000
                  deliveryMethod: HTTP
                  credentials:
                    apiUrl: https://api.provider.com/ddex/deliver
                    authType: bearer
                    bearerToken: eyJhbGciOiJIUzI1NiIs...
                    contentType: application/xml
                  priority: 50
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    $ref: '#/components/schemas/TenantDDEXProvider'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    ProviderCredentials:
      type: object
      description: >-
        Credentials for connecting to a DDEX provider. The required fields
        depend on the delivery method.

        - SFTP/FTP: host, username, password required

        - HTTP/API: apiUrl required, plus authentication fields

        - AS2: endpoint, as2From, as2To required
      oneOf:
        - $ref: '#/components/schemas/SFTPCredentials'
        - $ref: '#/components/schemas/HTTPCredentials'
        - $ref: '#/components/schemas/AS2Credentials'
        - $ref: '#/components/schemas/WebDAVCredentials'
    TenantDDEXProvider:
      type: object
      properties:
        id:
          type: string
          format: uuid
        TenantId:
          type: integer
        providerId:
          type: string
          format: uuid
        LabelId:
          type: string
          format: uuid
          nullable: true
        isEnabled:
          type: boolean
        deliveryMethod:
          type: string
          enum:
            - SFTP
            - WebService
            - API
            - FTP
        priority:
          type: integer
        customSettings:
          type: object
        rateLimits:
          type: object
        acknowledgementSettings:
          type: object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SFTPCredentials:
      type: object
      description: Credentials for SFTP/FTP delivery method
      required:
        - host
        - username
        - password
      properties:
        host:
          type: string
          description: FTP/SFTP server hostname or IP address
          example: ftp.provider.com
        port:
          type: integer
          description: Server port (default 22 for SFTP, 21 for FTP)
          default: 22
          example: 22
        username:
          type: string
          description: Login username
          example: myuser
        password:
          type: string
          format: password
          description: Login password (encrypted at rest)
          example: ••••••••
        remotePath:
          type: string
          description: Remote directory path for uploads
          default: /uploads
          example: /incoming/ddex
        secure:
          type: boolean
          description: Use secure connection (TLS/SSL)
          default: true
        passiveMode:
          type: boolean
          description: Use passive mode for FTP connections
          default: true
        privateKey:
          type: string
          description: SSH private key for key-based authentication (optional)
          nullable: true
    HTTPCredentials:
      type: object
      description: Credentials for HTTP/HTTPS API delivery method
      required:
        - apiUrl
      properties:
        apiUrl:
          type: string
          format: uri
          description: API endpoint URL
          example: https://api.provider.com/ddex/deliver
        method:
          type: string
          description: HTTP method to use
          enum:
            - GET
            - POST
            - PUT
          default: POST
        authType:
          type: string
          description: Authentication type
          enum:
            - bearer
            - basic
            - apiKey
            - oauth
            - none
          default: bearer
        bearerToken:
          type: string
          description: Bearer token for authentication
          example: eyJhbGciOiJIUzI1NiIs...
        username:
          type: string
          description: Username for basic auth
        password:
          type: string
          format: password
          description: Password for basic auth
        apiKey:
          type: string
          description: API key for apiKey authentication
        apiKeyHeader:
          type: string
          description: Header name for API key
          default: X-API-Key
          example: X-API-Key
        headers:
          type: object
          description: Custom HTTP headers
          additionalProperties:
            type: string
          example:
            X-Custom-Header: value
        contentType:
          type: string
          description: Content type for requests
          default: application/xml
          example: application/xml
        timeout:
          type: integer
          description: Request timeout in milliseconds
          default: 30000
    AS2Credentials:
      type: object
      description: Credentials for AS2 (Applicability Statement 2) delivery method
      required:
        - endpoint
        - as2From
        - as2To
      properties:
        endpoint:
          type: string
          format: uri
          description: AS2 endpoint URL
          example: https://as2.provider.com/receive
        as2From:
          type: string
          description: Sender AS2 identifier
          example: MYCOMPANY_AS2_ID
        as2To:
          type: string
          description: Receiver AS2 identifier
          example: PROVIDER_AS2_ID
        subject:
          type: string
          description: AS2 message subject
          default: DDEX Message
        signingEnabled:
          type: boolean
          description: Enable message signing
          default: false
        signingCertificate:
          type: string
          description: PEM-encoded signing certificate
        signingPrivateKey:
          type: string
          description: PEM-encoded private key for signing
        signingAlgorithm:
          type: string
          description: Signing algorithm
          enum:
            - SHA-1
            - SHA-256
            - SHA-384
            - SHA-512
          default: SHA-256
        encryptionEnabled:
          type: boolean
          description: Enable message encryption
          default: false
        encryptionCertificate:
          type: string
          description: PEM-encoded encryption certificate
        encryptionAlgorithm:
          type: string
          description: Encryption algorithm
          enum:
            - 3DES
            - AES128
            - AES192
            - AES256
          default: AES256
        receiptRequested:
          type: boolean
          description: Request MDN receipt
          default: true
        receiptSigned:
          type: boolean
          description: Request signed MDN receipt
          default: false
        receiptAsync:
          type: boolean
          description: Request asynchronous MDN receipt
          default: false
        receiptUrl:
          type: string
          format: uri
          description: URL for async MDN receipt
    WebDAVCredentials:
      type: object
      description: Credentials for WebDAV delivery method
      required:
        - url
        - username
        - password
      properties:
        url:
          type: string
          format: uri
          description: WebDAV server URL
          example: https://webdav.provider.com/uploads
        username:
          type: string
          description: WebDAV username
        password:
          type: string
          format: password
          description: WebDAV password
        remotePath:
          type: string
          description: Remote directory path
          default: /uploads
        realm:
          type: string
          description: Authentication realm (if required)
        createDirectories:
          type: boolean
          description: Automatically create directories if they don't exist
          default: true
        lockFiles:
          type: boolean
          description: Lock files during upload
          default: false
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Invalid request parameters
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Unauthorized
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Resource not found
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Authorization header using the Bearer scheme. Format: "Bearer
        {token}"

````