Create a Provider Configuration

Use this endpoint to create a new provider configuration. The configuration is validated against the provider’s JSON Schema.

POST /v1/provider-configurations

Create a Provider Configuration

cURL

curl --request POST \
  --url https://flowker.sandbox.lerian.net/v1/provider-configurations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config": {
    "baseUrl": "https://api.clearsale.com.br",
    "apiKey": "cs-key-abc123",
    "environment": "production"
  },
  "name": "ClearSale Production",
  "allowedHosts": [
    "api.acme.com",
    ".kyc-provider.io"
  ],
  "allowedPrivateHosts": [
    "nginx.pix-inline.internal"
  ],
  "kind": "external_openapi",
  "description": "ClearSale anti-fraud for Pix transactions",
  "metadata": {
    "environment": "production",
    "team": "risk"
  },
  "providerId": "clearsale",
  "schemaBindings": [
    {
      "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
      "type": "openapi",
      "operations": [
        {
          "method": "POST",
          "path": "/payments"
        }
      ]
    }
  ]
}
'

201

{
  "createdAt": "2026-03-17T14:00:00Z",
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "name": "ClearSale Production",
  "status": "active"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider. Send it in the Authorization header as Bearer <token>.

Body

application/json

Request body containing the provider configuration details.

config · object · required

Provider-specific configuration that is validated against the provider's JSON Schema.

Show child attributes

Example:

{
  "baseUrl": "https://api.clearsale.com.br",
  "apiKey": "cs-key-abc123",
  "environment": "production"
}

name · string · required

Unique name for this provider configuration.

Required string length: 1 - 100

Example:

"ClearSale Production"

allowedHosts · string[] | null

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.

Maximum array length: 100

Maximum string length: 253

Example:

["api.acme.com", ".kyc-provider.io"]

allowedPrivateHosts · string[] | null

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.

Maximum array length: 100

Maximum string length: 253

Example:

["nginx.pix-inline.internal"]

kind · enum<string>

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.

Available options: catalog, external_openapi

Example:

"external_openapi"

description · string

Human-readable description of this provider configuration.

Maximum string length: 500

Example:

"ClearSale anti-fraud for Pix transactions"

metadata · object

Custom key-value pairs for tagging.

Show child attributes

Example:

{
  "environment": "production",
  "team": "risk"
}

providerId · string

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"

schemaBindings · object[] | null

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.

Maximum array length: 100

Show child attributes

Response

201

application/json

Indicates that the resource was successfully created and the operation was completed as expected.

createdAt · string<date-time>

Timestamp when the configuration was created.

Example:

"2026-03-17T14:00:00Z"

id · string<uuid>

Unique identifier of the created configuration.

Example:

"c3d4e5f6-a7b8-9012-cdef-345678901234"

name · string

Name of the configuration.

Example:

"ClearSale Production"

status · string

Initial status (always active on creation).

Example:

"active"