Create a Provider Configuration

Use this endpoint to create a new provider configuration. The configuration is validated against the provider’s JSON Schema. A protected provider configuration is written only by a person: an application gets 403 FLK-0365 on create with protected true, update, enable, disable and delete.

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"
        }
      ]
    }
  ],
  "protected": true
}
'

201

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

Autorizaciones

Authorization · string · header · requerido

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

Cuerpo

application/json

Request body containing the provider configuration details.

config · object · requerido

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

Show child attributes

Ejemplo:

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

name · string · requerido

Unique name for this provider configuration.

Required string length: 1 - 100

Ejemplo:

"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

Ejemplo:

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

allowedPrivateHosts · string[] | null

Named private-host allowance, managed by Lerian. A request from your tenant that sets a non-empty list answers 422 FLK-0317.

Maximum array length: 100

Maximum string length: 253

Ejemplo:

["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 ignored for that kind, which always stores external.openapi, and its config holds openapi_schema_id plus an optional auth block and base_url. You choose the kind when you create the configuration.

Opciones disponibles: catalog, external_openapi

Ejemplo:

"external_openapi"

description · string

Human-readable description of this provider configuration.

Maximum string length: 500

Ejemplo:

"ClearSale anti-fraud for Pix transactions"

metadata · object

Custom key-value pairs for tagging.

Show child attributes

Ejemplo:

{
  "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.

Ejemplo:

"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

protected · boolean

Set at creation only. Only a person changes, enables, disables or deletes a protected configuration. A workflow that uses it is activated only by a person, and only with a non-empty allowedCallers list.

Ejemplo:

true

Respuesta

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.

Ejemplo:

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

id · string<uuid>

Unique identifier of the created configuration.

Ejemplo:

"c3d4e5f6-a7b8-9012-cdef-345678901234"

name · string

Name of the configuration.

Ejemplo:

"ClearSale Production"

status · string

Initial status (always active on creation).

Ejemplo:

"active"