> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a Provider Configuration > Use this endpoint to create a new provider configuration. The configuration is validated against the provider's JSON Schema. ## OpenAPI ````yaml en/openapi/v3-current/flowker.yaml post /v1/provider-configurations openapi: 3.1.0 info: description: >- Complete API reference for Flowker workflow orchestration services including catalog management, workflow definitions, executor configurations, provider configurations, and workflow executions. title: Flowker API version: 1.2.0 servers: - url: https://flowker.sandbox.lerian.net security: - BearerAuth: [] tags: - name: Catalog API description: >- Browse built-in providers, executors, and triggers available in the Flowker catalog. - name: Workflows API description: >- Create, update, activate, deactivate, clone, and delete workflow definitions. - name: Executions API description: Start workflow executions and track their status and results. - name: Executor Configurations API description: >- List, inspect, update, and delete the executor configuration records a deployment holds. - name: Provider Configurations API description: >- Create, update, enable, and disable the provider configurations that workflow nodes call through. - name: Dashboard API description: >- Retrieve aggregated summaries of workflows and executions for operational dashboards. - name: Webhooks API description: >- Receive webhook callbacks from external systems to trigger workflow executions. - name: Schedule API description: >- Inspect a workflow's upcoming, skipped, and parked scheduled occurrences, and run or discard the parked ones. - name: Schema Registry API description: >- Publish global OpenAPI specification versions for native services and pin the version each tenant resolves against. - name: OpenAPI Schemas API description: >- Upload, inspect, and delete the tenant's external OpenAPI schemas, and derive the contract of a single operation. - name: XSD Schemas API description: >- Upload, inspect, and delete the tenant's XSD schemas used to validate XML webhook payloads. paths: /v1/provider-configurations: post: tags: - Provider Configurations API summary: Create a Provider Configuration description: >- Use this endpoint to create a new provider configuration. The configuration is validated against the provider's JSON Schema. operationId: createProviderConfiguration requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateProviderConfigurationInput' description: Request body containing the provider configuration details. required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ProviderConfigurationCreateOutput' description: >- Indicates that the resource was successfully created and the operation was completed as expected. '400': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates that the request was malformed or contained invalid parameters. '404': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: Indicates that the requested resource could not be found. '409': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates that the request could not be completed due to a conflict with the current state of the resource. '422': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates that the request was well-formed but contains semantic errors that prevent processing. '500': content: application/problem+json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Indicates an unexpected internal error. If this persists, please contact support. components: schemas: CreateProviderConfigurationInput: properties: allowedHosts: description: >- Outbound allow-list of destination hostnames. It applies to every node that calls through this configuration. Omit the field, or send an empty list, to accept any public host. The generic HTTP connector, provider id `http`, is the exception — it rejects an empty list with error `FLK-0323`. A leading dot matches subdomains, so ".kyc-provider.io" matches "api.kyc-provider.io". Entries are hostnames only, with no IP literal, no wildcard and no port. Flowker lowercases every entry. Flowker checks the `base_url`, `onboarding_base_url` and `transaction_base_url` values in `config` against this list, and it checks the request URL and every redirect hop at run time. items: maxLength: 253 type: string maxItems: 100 type: - array - 'null' example: - api.acme.com - .kyc-provider.io allowedPrivateHosts: description: >- Named private-host allowance, managed by your operations team. An entry lets this configuration call a host that resolves to a private or loopback address, which Flowker blocks by default. Cloud metadata and link-local addresses stay blocked, and no entry reaches them. Entries follow the same format as allowedHosts. items: maxLength: 253 type: string maxItems: 100 type: - array - 'null' example: - nginx.pix-inline.internal config: additionalProperties: type: object description: >- Provider-specific configuration that is validated against the provider's JSON Schema. example: baseUrl: https://api.clearsale.com.br apiKey: cs-key-abc123 environment: production type: object kind: description: >- Which kind of connection this is. Omit it, or send "catalog", for a connection to a catalog provider — `providerId` is then required. Send "external_openapi" for a connection to an OpenAPI document you uploaded through the OpenAPI schema registry; `providerId` is optional for that kind, and its `config` holds `openapi_schema_id` plus an optional `auth` block and `base_url`. You choose the kind when you create the configuration. enum: - catalog - external_openapi example: external_openapi type: string description: description: Human-readable description of this provider configuration. example: ClearSale anti-fraud for Pix transactions maxLength: 500 type: string metadata: additionalProperties: type: object description: Custom key-value pairs for tagging. example: environment: production team: risk type: object name: description: Unique name for this provider configuration. example: ClearSale Production maxLength: 100 minLength: 1 type: string providerId: description: >- ID of the catalog provider to configure. It is required for the `catalog` kind, and Flowker rejects a create that omits it with error `FLK-0297`. A configuration of kind `external_openapi` may omit it, and a read of that configuration returns the reserved id `external.openapi`. example: clearsale type: string schemaBindings: description: >- Stored schemas this configuration binds to. Each entry names one XSD or OpenAPI schema already registered for your tenant. Omit the field, or send an empty list, for no bindings. Two identical entries in the same request are rejected. items: $ref: '#/components/schemas/SchemaBindingInput' maxItems: 100 type: - array - 'null' required: - config - name type: object ProviderConfigurationCreateOutput: properties: createdAt: description: Timestamp when the configuration was created. example: '2026-03-17T14:00:00Z' format: date-time type: string id: description: Unique identifier of the created configuration. example: c3d4e5f6-a7b8-9012-cdef-345678901234 format: uuid type: string name: description: Name of the configuration. example: ClearSale Production type: string status: description: Initial status (always `active` on creation). example: active type: string type: object ErrorResponse: properties: code: description: Stable, machine-readable Flowker error code. example: FLK-0001 type: string detail: description: >- Human-readable explanation of this occurrence. Responses with a status of 500 or above carry a fixed generic message. example: name is a required field type: string errors: description: Per-field entries for a request that failed validation. items: $ref: '#/components/schemas/ErrorDetail' type: array instance: description: URI reference identifying this specific occurrence. example: /v1/workflows format: uri type: string status: description: HTTP status code. example: 400 type: integer title: description: >- Standard HTTP reason phrase for the status. It does not change per error code. example: Bad Request type: string type: description: >- URI reference identifying the error. Always the error catalog base followed by the code. example: https://errors.lerian.studio/v1/FLK-0001 format: uri type: string type: object SchemaBindingInput: description: One binding between a provider configuration and a stored schema. properties: operations: description: >- Restricts an OpenAPI binding to the listed operations. Omit it, or send null, to bind the whole document. Only a binding of type "openapi" accepts operations. items: $ref: '#/components/schemas/SchemaBindingOperationInput' maxItems: 100 type: - array - 'null' schemaId: description: Identifier of the stored schema, as a UUID. example: 018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8 type: string type: description: Which schema registry the binding points at. enum: - xsd - openapi example: openapi type: string required: - schemaId - type type: object ErrorDetail: properties: location: description: Where the problem is, such as body.nodes or path.id. example: body.nodes type: string message: description: Description of the field-level problem. example: expected array length >= 1 type: string value: description: The value that caused the error, when it is safe to echo. type: object SchemaBindingOperationInput: description: One operation of a bound OpenAPI document. properties: method: description: >- HTTP method of the operation. One of GET, PUT, POST, DELETE, OPTIONS, HEAD, PATCH or TRACE. Flowker uppercases the value. example: POST maxLength: 10 type: string path: description: Path of the operation. It must start with a slash. example: /payments maxLength: 2048 type: string required: - method - path type: object securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token issued by the identity provider. Send it in the Authorization header as `Bearer `. ````