admin

Version 0.1.011 operations

Konnect admin and support: affiliations across organisations

GET/admin/affiliationsDashboard session

Parameters

cursoranyquery
limitintegerquery
- max: 200
- default: 50
statusanyquery
provideranyquery
organisationanyquery
Organisation id

Responses

200
- itemsAdminAffiliationDto[]required
  - idstring (uuid)required
  - organisationIdstring (uuid)required
  - providerstringrequired
    - enum: "clictopay", "flouci", "izi", "mpgs_poste", "pluxee", "kashy", "enda_tao"
  - providerNamestringrequired
  - labelstringrequired
  - environmentstringrequired
    - enum: "sandbox", "production"
  - statusstringrequired
    - enum: "draft", "verifying", "active", "suspended", "revoked"
  - publicIdentifierstring | nullrequired
    Never a secret
  - credentialsobjectrequired
    Non-secret fields in full, secret fields as **** plus their last four characters; never a value usable at the provider
  - credentialVersionnumberrequired
    Current credential version, 1 for the first credentials
  - verifiedAtstring (date-time) | nullrequired
  - lastUsedAtstring (date-time) | nullrequired
  - lastVerificationErrorstring | nullrequired
    Readable, never a secret
  - revokedAtstring (date-time) | nullrequired
  - paymentAccountsRoutedPaymentAccountDto[]required
    Payment accounts whose routing uses this affiliation; they lose it on revoke
    - idstring (uuid)required
    - namestringrequired
    - statusstringrequired
      - enum: "active", "paused", "archived"
  - createdAtstring (date-time)required
  - updatedAtstring (date-time)required
  - organisationNamestringrequired
- nextCursorstring | nullrequired

Code samples

curl -X GET "$KONNECT_API_URL/admin/affiliations" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "items": [
    {
      "id": "id",
      "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
      "provider": "clictopay",
      "providerName": "ClicToPay",
      "label": "default",
      "environment": "sandbox",
      "status": "draft",
      "publicIdentifier": "publicIdentifier",
      "credentials": {},
      "credentialVersion": 1,
      "verifiedAt": "2026-10-01T09:30:00.000Z",
      "lastUsedAt": "2026-10-01T09:30:00.000Z",
      "lastVerificationError": "lastVerificationError",
      "revokedAt": "2026-10-01T09:30:00.000Z",
      "paymentAccounts": [
        {
          "id": "id",
          "name": "name",
          "status": "active"
        }
      ],
      "createdAt": "2026-10-01T09:30:00.000Z",
      "updatedAt": "2026-10-01T09:30:00.000Z",
      "organisationName": "organisationName"
    }
  ],
  "nextCursor": "nextCursor"
}

Outbox events, newest first (Konnect support)

GET/admin/outboxDashboard session

Parameters

cursoranyquery
nextCursor of the previous page
limitintegerquery
- max: 200
- default: 50
statusstringquery
- enum: "pending", "done", "failed"

Responses

200
- itemsOutboxEventDto[]required
  - idstring (uuid)required
  - typestringrequired
  - statusstringrequired
    - enum: "pending", "done", "failed"
  - payloadobjectrequired
    Redacted payload
  - attemptsnumberrequired
  - lastErrorstring | null
  - runAtstring (date-time)required
  - doneAtstring (date-time) | null
  - createdAtstring (date-time)required
- nextCursorstring | nullrequired
401Not authenticated; 403 for anyone but Konnect support and admins

Code samples

curl -X GET "$KONNECT_API_URL/admin/outbox" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "items": [
    {
      "id": "id",
      "type": "email.send",
      "status": "pending",
      "payload": {},
      "attempts": 1,
      "lastError": "lastError",
      "runAt": "2026-10-01T09:30:00.000Z",
      "doneAt": "2026-10-01T09:30:00.000Z",
      "createdAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "nextCursor": "nextCursor"
}

Konnect staff: every organisation with its status facts

GET/admin/organisationsDashboard session

Parameters

No parameters.

Responses

200
- idstring (uuid)required
- namestringrequired
- legalNamestringrequired
- taxIdstringrequired
- kybStatusstringrequired
  - enum: "pending", "verified", "refused"
- contractSignedAtstring (date-time) | nullrequired
- canCollectbooleanrequired
- reasonsstring[]required
- memberCountnumberrequired
- createdAtstring (date-time)required

Code samples

curl -X GET "$KONNECT_API_URL/admin/organisations" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

[
  {
    "id": "id",
    "name": "name",
    "legalName": "legalName",
    "taxId": "taxId",
    "kybStatus": "pending",
    "contractSignedAt": "2026-10-01T09:30:00.000Z",
    "canCollect": true,
    "reasons": [
      "kyb_pending"
    ],
    "memberCount": 1,
    "createdAt": "2026-10-01T09:30:00.000Z"
  }
]

Konnect staff: identity and status facts of one organisation

GET/admin/organisations/{id}Dashboard session

Parameters

idstringpathrequired

Responses

200
- idstring (uuid)required
- namestringrequired
- legalNamestringrequired
- taxIdstringrequired
- countrystringrequired
- addressstring | nullrequired
- citystring | nullrequired
- postalCodestring | nullrequired
- phonestring | nullrequired
- emailstring | nullrequired
- websitestring | nullrequired
- kybStatusstringrequired
  - enum: "pending", "verified", "refused"
- contractSignedAtstring (date-time) | nullrequired
- activeAffiliationsnumberrequired
- canCollectbooleanrequired
  Computed: KYB verified, contract signed, one active affiliation
- reasonsstring[]required
- paymentAccountsPaymentAccountSummaryDto[]required
  Accounts within your scope
  - idstring (uuid)required
  - namestringrequired
  - slugstringrequired
  - isDefaultbooleanrequired
  - statusstringrequired
    - enum: "active", "paused", "archived"

Code samples

curl -X GET "$KONNECT_API_URL/admin/organisations/id" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "id": "id",
  "name": "name",
  "legalName": "legalName",
  "taxId": "taxId",
  "country": "country",
  "address": "address",
  "city": "city",
  "postalCode": "postalCode",
  "phone": "phone",
  "email": "buyer@example.com",
  "website": "website",
  "kybStatus": "pending",
  "contractSignedAt": "2026-10-01T09:30:00.000Z",
  "activeAffiliations": 1,
  "canCollect": true,
  "reasons": [
    "kyb_pending"
  ],
  "paymentAccounts": [
    {
      "id": "id",
      "name": "name",
      "slug": "slug",
      "isDefault": true,
      "status": "active"
    }
  ]
}

Full timeline of any payment, with raw provider payloads (admin)

GET/admin/payments/{reference}/timelineDashboard session

Parameters

referencestringpathrequired
categorystring[]query
Repeat to keep several categories; all by default
cursoranyquery
nextCursor of the previous page
limitintegerquery
- max: 200
- default: 100

Responses

200
- paymentPaymentDtorequired
  - idstring (uuid)required
  - referencestringrequired
    24 hexadecimal characters
  - statusstringrequired
    - enum: "pending", "succeeded", "failed", "expired", "canceled"
  - amountnumberrequired
  - currencystringrequired
  - descriptionstring | nullrequired
  - orderIdstring | nullrequired
  - payerPayerDtorequired
    - firstNamestring
    - lastNamestring
    - emailstring
      Receives the receipt
    - phonestring
  - acceptedProvidersstring[]required
  - providerstring | nullrequired
    Provider of the succeeded attempt, or of the last attempt opened
  - organisationIdstring (uuid)required
  - paymentAccountIdstring (uuid)required
  - channelstringrequired
    - enum: "api", "link", "konnect_me", "plugin_woocommerce", "plugin_prestashop", "plugin_whmcs", "compat_v2"
  - successUrlstring | nullrequired
  - failUrlstring | nullrequired
  - webhookUrlstring | nullrequired
  - expiresAtstring (date-time)required
  - metadataobjectrequired
  - payUrlstringrequired
    Hosted checkout page of this payment
  - succeededAttemptIdstring (uuid) | nullrequired
  - attemptsCountnumberrequired
  - paymentLinkIdstring (uuid) | nullrequired
    The payment link the payer started from (channel link), null otherwise
  - resultany
    Result summary (API responses only, not in webhook bodies)
  - createdAtstring (date-time)required
  - updatedAtstring (date-time)required
- attemptsTimelineAttemptDto[]required
  Oldest first
  - idstring (uuid)required
  - numbernumberrequired
    1 for the first attempt of the payment
  - providerstringrequired
  - statusstringrequired
  - externalRefstring | nullrequired
  - amountnumberrequired
  - providerFeenumber | nullrequired
  - affiliationAttemptAffiliationDtorequired
    - affiliationIdstring (uuid)required
    - labelstringrequired
    - environmentstringrequired
      - enum: "sandbox", "production"
    - publicIdentifierstring | nullrequired
      Never a secret
    - credentialVersionnumberrequired
  - checksCountnumberrequired
  - resultAttemptResultDtorequired
    - failureCodestring | nullrequired
      - enum: "declined", "insufficient_funds", "limit_exceeded", "card_expired", "invalid_instrument", "authentication_failed", "fraud_suspected", "canceled_by_payer", "session_expired", "payment_expired", "provider_unavailable", "invalid_request", "merchant_auth_failed", "unknown_reference", "unknown"
    - providerResultCodestring | nullrequired
      The provider own code
    - providerMessagestring | nullrequired
      The provider message, redacted
    - authorizationCodestring | nullrequired
    - instrumentany | nullrequired
    - initiatedAtstring (date-time) | nullrequired
    - redirectedAtstring (date-time) | nullrequired
    - authorizedAtstring (date-time) | nullrequired
    - completedAtstring (date-time) | nullrequired
    - durationsAttemptDurationsDtorequired
      - initMsnumber | nullrequired
        initiated_at to redirected_at
      - payerMsnumber | nullrequired
        redirected_at to completed_at
      - totalMsnumber | nullrequired
        initiated_at to completed_at
  - createdAtstring (date-time)required
  - rawany
    Admin view only
- webhooksTimelineWebhooksDtorequired
  - deliveriesWebhookDeliveryDto[]required
    - idstring (uuid)required
    - endpointIdstring (uuid)required
    - paymentIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - statusstringrequired
      - enum: "pending", "delivered", "failed"
    - attemptsnumberrequired
    - lastStatusCodenumber | nullrequired
    - lastErrorstring | nullrequired
    - lastAttemptAtstring (date-time) | nullrequired
    - deliveredAtstring (date-time) | nullrequired
    - lastOutcomestring | nullrequired
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - nextRetryAtstring (date-time) | nullrequired
    - manualTriesnumberrequired
    - createdAtstring (date-time)required
  - triesWebhookTryDto[]required
    Every HTTP try, oldest first
    - idstring (uuid)required
    - deliveryIdstring (uuid)required
    - endpointIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - tryNumbernumberrequired
    - triggerstringrequired
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullrequired
    - requestHeadersobjectrequired
    - requestBodystringrequired
      The body as sent, byte for byte
    - startedAtstring (date-time)required
    - durationMsnumberrequired
    - outcomestringrequired
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - statusCodenumber | nullrequired
    - responseHeadersobject | nullrequired
    - responseExcerptstring | nullrequired
      First 2 KB, redacted
    - errorMessagestring | nullrequired
    - nextRetryAtstring (date-time) | nullrequired
- itemsTimelineItemDto[]required
  Oldest first
  - idstring (uuid)required
  - seqstringrequired
    Timeline order, shared by the three source tables
  - kindstringrequired
    - enum: "payment_event", "attempt_event"
  - typestringrequired
  - categorystringrequired
    - enum: "payment", "checkout", "attempt", "notification", "email", "anomaly", "refund", "reconciliation"
  - occurredAtstring (date-time)required
  - attemptIdstring (uuid) | nullrequired
  - actorTimelineActorDtorequired
    - typestringrequired
      - enum: "system", "merchant_user", "api_key", "payer", "provider", "admin"
    - idstring | nullrequired
      User or API key id
  - sourcestringrequired
    - enum: "merchant_api", "dashboard", "checkout", "provider_callback", "poller", "outbox_worker", "admin_console", "system", "init", "callback", "poll", "manual"
  - fromStatusstring | nullrequired
  - toStatusstring | nullrequired
  - detailsobjectrequired
    Redacted
  - attemptEventAttemptEventDto
    - idstring (uuid)required
    - typestringrequired
    - fromStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - toStatusstring | nullrequired
      - enum: "created", "redirected", "pending", "succeeded", "failed", "canceled", "expired", "refunded"
    - sourcestringrequired
      - enum: "init", "callback", "poll", "manual"
    - detailsobjectrequired
      Redacted
    - createdAtstring (date-time)required
  - webhookTryWebhookTryDto
    - idstring (uuid)required
    - deliveryIdstring (uuid)required
    - endpointIdstring (uuid)required
    - eventIdstring (uuid)required
    - eventTypestringrequired
      - enum: "payment.succeeded", "payment.failed", "payment.expired", "payment.canceled", "attempt.duplicate_success"
    - urlstringrequired
    - tryNumbernumberrequired
    - triggerstringrequired
      - enum: "automatic", "manual"
    - requestedBystring (uuid) | nullrequired
    - requestHeadersobjectrequired
    - requestBodystringrequired
      The body as sent, byte for byte
    - startedAtstring (date-time)required
    - durationMsnumberrequired
    - outcomestringrequired
      - enum: "delivered", "http_4xx", "http_5xx", "timeout", "connection_refused", "dns_error", "tls_error", "redirect_not_followed", "response_too_large", "invalid_url_or_blocked", "other"
    - statusCodenumber | nullrequired
    - responseHeadersobject | nullrequired
    - responseExcerptstring | nullrequired
      First 2 KB, redacted
    - errorMessagestring | nullrequired
    - nextRetryAtstring (date-time) | nullrequired
- nextCursorstring | nullrequired
- eventTypesVersionnumberrequired
  PAYMENT_EVENT_TYPES_VERSION of packages/domain
401Not authenticated; 403 for anyone but konnect_admin
404payment_not_found

Code samples

curl -X GET "$KONNECT_API_URL/admin/payments/reference/timeline" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "payment": {
    "id": "id",
    "reference": "665f1c2e8b3a4d0012ab34cd",
    "status": "pending",
    "amount": 12500,
    "currency": "TND",
    "description": "description",
    "orderId": "order-1001",
    "payer": {
      "firstName": "Sami",
      "lastName": "Test",
      "email": "payer@example.test",
      "phone": "+21600000000"
    },
    "acceptedProviders": [
      "clictopay"
    ],
    "provider": "provider",
    "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
    "paymentAccountId": "paymentAccountId",
    "channel": "api",
    "successUrl": "successUrl",
    "failUrl": "failUrl",
    "webhookUrl": "webhookUrl",
    "expiresAt": "2026-10-01T09:30:00.000Z",
    "metadata": {},
    "payUrl": "payUrl",
    "succeededAttemptId": "succeededAttemptId",
    "attemptsCount": 1,
    "paymentLinkId": "paymentLinkId",
    "result": {
      "status": "pending",
      "provider": "provider",
      "attemptId": "attemptId",
      "failureCode": "declined",
      "authorizationCode": "authorizationCode",
      "instrument": {
        "type": null,
        "brand": null,
        "last4": null,
        "maskedId": null
      },
      "attemptsCount": 1,
      "failedAttemptsCount": 1,
      "checkoutOpensCount": 1,
      "firstOpenedAt": "2026-10-01T09:30:00.000Z",
      "completedAt": "2026-10-01T09:30:00.000Z",
      "durationMs": 1,
      "merchantConfirmation": "confirmed",
      "merchantConfirmationReason": {
        "outcome": null,
        "statusCode": null,
        "tries": null,
        "timeoutMs": null,
        "endpointDisabled": null,
        "nextRetryAt": null,
        "deliveryId": null
      }
    },
    "createdAt": "2026-10-01T09:30:00.000Z",
    "updatedAt": "2026-10-01T09:30:00.000Z"
  },
  "attempts": [
    {
      "id": "id",
      "number": 1,
      "provider": "provider",
      "status": "status",
      "externalRef": "externalRef",
      "amount": 1,
      "providerFee": 1,
      "affiliation": {
        "affiliationId": "affiliationId",
        "label": "default",
        "environment": "sandbox",
        "publicIdentifier": "publicIdentifier",
        "credentialVersion": 1
      },
      "checksCount": 1,
      "result": {
        "failureCode": "declined",
        "providerResultCode": "providerResultCode",
        "providerMessage": "providerMessage",
        "authorizationCode": "authorizationCode",
        "instrument": {
          "type": null,
          "brand": null,
          "last4": null,
          "maskedId": null
        },
        "initiatedAt": "2026-10-01T09:30:00.000Z",
        "redirectedAt": "2026-10-01T09:30:00.000Z",
        "authorizedAt": "2026-10-01T09:30:00.000Z",
        "completedAt": "2026-10-01T09:30:00.000Z",
        "durations": {
          "initMs": 1,
          "payerMs": 1,
          "totalMs": 1
        }
      },
      "createdAt": "2026-10-01T09:30:00.000Z",
      "raw": {
        "rawInit": {},
        "rawStatus": {},
        "rawCallback": {}
      }
    }
  ],
  "webhooks": {
    "deliveries": [
      {
        "id": "id",
        "endpointId": "endpointId",
        "paymentId": "665f1c2e8b3a4d0012ab34cd",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "status": "pending",
        "attempts": 1,
        "lastStatusCode": 1,
        "lastError": "lastError",
        "lastAttemptAt": "2026-10-01T09:30:00.000Z",
        "deliveredAt": "2026-10-01T09:30:00.000Z",
        "lastOutcome": "delivered",
        "nextRetryAt": "2026-10-01T09:30:00.000Z",
        "manualTries": 1,
        "createdAt": "2026-10-01T09:30:00.000Z"
      }
    ],
    "tries": [
      {
        "id": "id",
        "deliveryId": "deliveryId",
        "endpointId": "endpointId",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "tryNumber": 1,
        "trigger": "automatic",
        "requestedBy": "requestedBy",
        "requestHeaders": {},
        "requestBody": "requestBody",
        "startedAt": "2026-10-01T09:30:00.000Z",
        "durationMs": 1,
        "outcome": "delivered",
        "statusCode": 1,
        "responseHeaders": {},
        "responseExcerpt": "responseExcerpt",
        "errorMessage": "errorMessage",
        "nextRetryAt": "2026-10-01T09:30:00.000Z"
      }
    ]
  },
  "items": [
    {
      "id": "id",
      "seq": "seq",
      "kind": "payment_event",
      "type": "attempt_status_changed",
      "category": "payment",
      "occurredAt": "2026-10-01T09:30:00.000Z",
      "attemptId": "attemptId",
      "actor": {
        "type": "system",
        "id": "id"
      },
      "source": "merchant_api",
      "fromStatus": "fromStatus",
      "toStatus": "toStatus",
      "details": {},
      "attemptEvent": {
        "id": "id",
        "type": "transition",
        "fromStatus": "created",
        "toStatus": "created",
        "source": "init",
        "details": {},
        "createdAt": "2026-10-01T09:30:00.000Z"
      },
      "webhookTry": {
        "id": "id",
        "deliveryId": "deliveryId",
        "endpointId": "endpointId",
        "eventId": "eventId",
        "eventType": "payment.succeeded",
        "url": "url",
        "tryNumber": 1,
        "trigger": "automatic",
        "requestedBy": "requestedBy",
        "requestHeaders": {},
        "requestBody": "requestBody",
        "startedAt": "2026-10-01T09:30:00.000Z",
        "durationMs": 1,
        "outcome": "delivered",
        "statusCode": 1,
        "responseHeaders": {},
        "responseExcerpt": "responseExcerpt",
        "errorMessage": "errorMessage",
        "nextRetryAt": "2026-10-01T09:30:00.000Z"
      }
    }
  ],
  "nextCursor": "nextCursor",
  "eventTypesVersion": 1
}

Every platform setting with its value or secret hint and source

GET/admin/settingsDashboard session

Parameters

No parameters.

Responses

200
- keystringrequired
- categorystringrequired
  - enum: "email", "platform", "payments"
- descriptionstringrequired
  English help text
- typeSettingTypeDtorequired
  - kindstringrequired
    - enum: "string", "email", "integer", "boolean", "enum", "string_list", "secret"
  - maxLengthnumber
    string: maximum length
  - minnumber
    integer: minimum
  - maxnumber
    integer: maximum
  - optionsstring[]
    enum: allowed values
  - maxItemsnumber
    string_list: maximum number of entries
- nullablebooleanrequired
  Accepts null (no value)
- secretbooleanrequired
  Write-only: the value is never returned
- requiresReauthbooleanrequired
  A write needs a re-authentication in the last 10 minutes
- visibleWhenany | nullrequired
- valuestring | number | boolean | string[]required
  Effective value (string, number, boolean or list); always null for secrets
- defaultValuestring | number | boolean | string[]required
  Code default; always null for secrets
- sourcestringrequired
  - enum: "database", "environment", "default"
- secretSetbooleanrequired
  Secrets: a value is stored
- secretLast4string | nullrequired
  Secrets: last four characters
- versionnumberrequired
  Version of the database value, 0 when none
- updatedAtstring (date-time) | nullrequired
- updatedBystring (uuid) | nullrequired
- storedValueInvalidbooleanrequired
  The stored value fails the current schema; the fallback applies
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes

Code samples

curl -X GET "$KONNECT_API_URL/admin/settings" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

[
  {
    "key": "email.transport",
    "category": "email",
    "description": "description",
    "type": {
      "kind": "string",
      "maxLength": 1,
      "min": 1,
      "max": 1,
      "options": [
        "string"
      ],
      "maxItems": 1
    },
    "nullable": true,
    "secret": true,
    "requiresReauth": true,
    "visibleWhen": {
      "key": "email.transport",
      "equals": [
        "smtp"
      ]
    },
    "value": "value",
    "defaultValue": "defaultValue",
    "source": "database",
    "secretSet": true,
    "secretLast4": "secretLast4",
    "version": 1,
    "updatedAt": "2026-10-01T09:30:00.000Z",
    "updatedBy": "updatedBy",
    "storedValueInvalid": true
  }
]

Send a test e-mail through the current e-mail settings

POST/admin/settings/email/testDashboard session

Parameters

No parameters.

Request body application/json

tostring
Recipient; the admin's own address when omitted

Responses

200
- statusstringrequired
  - enum: "sent", "suppressed"
- transportstringrequired
  - enum: "ses", "smtp", "log"
- messageIdstring
- reasonstring
  - enum: "not_in_allowlist", "allowlist_required"
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes
502email_delivery_failed (reason: AWS error name or SMTP code) or email_not_configured

Code samples

curl -X POST "$KONNECT_API_URL/admin/settings/email/test" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "to"
}'

Example: request body

{
  "to": "to"
}

Example: 200

{
  "status": "sent",
  "transport": "ses",
  "messageId": "messageId",
  "reason": "not_in_allowlist"
}

One platform setting

GET/admin/settings/{key}Dashboard session

Parameters

keystringpathrequired

Responses

200
- keystringrequired
- categorystringrequired
  - enum: "email", "platform", "payments"
- descriptionstringrequired
  English help text
- typeSettingTypeDtorequired
  - kindstringrequired
    - enum: "string", "email", "integer", "boolean", "enum", "string_list", "secret"
  - maxLengthnumber
    string: maximum length
  - minnumber
    integer: minimum
  - maxnumber
    integer: maximum
  - optionsstring[]
    enum: allowed values
  - maxItemsnumber
    string_list: maximum number of entries
- nullablebooleanrequired
  Accepts null (no value)
- secretbooleanrequired
  Write-only: the value is never returned
- requiresReauthbooleanrequired
  A write needs a re-authentication in the last 10 minutes
- visibleWhenany | nullrequired
- valuestring | number | boolean | string[]required
  Effective value (string, number, boolean or list); always null for secrets
- defaultValuestring | number | boolean | string[]required
  Code default; always null for secrets
- sourcestringrequired
  - enum: "database", "environment", "default"
- secretSetbooleanrequired
  Secrets: a value is stored
- secretLast4string | nullrequired
  Secrets: last four characters
- versionnumberrequired
  Version of the database value, 0 when none
- updatedAtstring (date-time) | nullrequired
- updatedBystring (uuid) | nullrequired
- storedValueInvalidbooleanrequired
  The stored value fails the current schema; the fallback applies
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes
404setting_not_found

Code samples

curl -X GET "$KONNECT_API_URL/admin/settings/key" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "key": "email.transport",
  "category": "email",
  "description": "description",
  "type": {
    "kind": "string",
    "maxLength": 1,
    "min": 1,
    "max": 1,
    "options": [
      "string"
    ],
    "maxItems": 1
  },
  "nullable": true,
  "secret": true,
  "requiresReauth": true,
  "visibleWhen": {
    "key": "email.transport",
    "equals": [
      "smtp"
    ]
  },
  "value": "value",
  "defaultValue": "defaultValue",
  "source": "database",
  "secretSet": true,
  "secretLast4": "secretLast4",
  "version": 1,
  "updatedAt": "2026-10-01T09:30:00.000Z",
  "updatedBy": "updatedBy",
  "storedValueInvalid": true
}

Change a platform setting (reason required); applies to every API process

PUT/admin/settings/{key}Dashboard session

Parameters

keystringpathrequired

Request body application/json

valuestring | number | boolean | string[]required
New value; for a secret, the plain value (never returned)
reasonstringrequired
- minLength: 3
- maxLength: 500
expectedVersionnumber
Version read before editing; 409 when it changed

Responses

200
- keystringrequired
- categorystringrequired
  - enum: "email", "platform", "payments"
- descriptionstringrequired
  English help text
- typeSettingTypeDtorequired
  - kindstringrequired
    - enum: "string", "email", "integer", "boolean", "enum", "string_list", "secret"
  - maxLengthnumber
    string: maximum length
  - minnumber
    integer: minimum
  - maxnumber
    integer: maximum
  - optionsstring[]
    enum: allowed values
  - maxItemsnumber
    string_list: maximum number of entries
- nullablebooleanrequired
  Accepts null (no value)
- secretbooleanrequired
  Write-only: the value is never returned
- requiresReauthbooleanrequired
  A write needs a re-authentication in the last 10 minutes
- visibleWhenany | nullrequired
- valuestring | number | boolean | string[]required
  Effective value (string, number, boolean or list); always null for secrets
- defaultValuestring | number | boolean | string[]required
  Code default; always null for secrets
- sourcestringrequired
  - enum: "database", "environment", "default"
- secretSetbooleanrequired
  Secrets: a value is stored
- secretLast4string | nullrequired
  Secrets: last four characters
- versionnumberrequired
  Version of the database value, 0 when none
- updatedAtstring (date-time) | nullrequired
- updatedBystring (uuid) | nullrequired
- storedValueInvalidbooleanrequired
  The stored value fails the current schema; the fallback applies
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes
404setting_not_found
409setting_version_conflict

Code samples

curl -X PUT "$KONNECT_API_URL/admin/settings/key" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "value": "value",
  "reason": "Switch to SES in eu-west-1",
  "expectedVersion": 1
}'

Example: request body

{
  "value": "value",
  "reason": "Switch to SES in eu-west-1",
  "expectedVersion": 1
}

Example: 200

{
  "key": "email.transport",
  "category": "email",
  "description": "description",
  "type": {
    "kind": "string",
    "maxLength": 1,
    "min": 1,
    "max": 1,
    "options": [
      "string"
    ],
    "maxItems": 1
  },
  "nullable": true,
  "secret": true,
  "requiresReauth": true,
  "visibleWhen": {
    "key": "email.transport",
    "equals": [
      "smtp"
    ]
  },
  "value": "value",
  "defaultValue": "defaultValue",
  "source": "database",
  "secretSet": true,
  "secretLast4": "secretLast4",
  "version": 1,
  "updatedAt": "2026-10-01T09:30:00.000Z",
  "updatedBy": "updatedBy",
  "storedValueInvalid": true
}

Delete the database value: the environment or code default applies

POST/admin/settings/{key}/resetDashboard session

Parameters

keystringpathrequired

Request body application/json

reasonstringrequired
- minLength: 3
- maxLength: 500
expectedVersionnumber

Responses

200
- keystringrequired
- categorystringrequired
  - enum: "email", "platform", "payments"
- descriptionstringrequired
  English help text
- typeSettingTypeDtorequired
  - kindstringrequired
    - enum: "string", "email", "integer", "boolean", "enum", "string_list", "secret"
  - maxLengthnumber
    string: maximum length
  - minnumber
    integer: minimum
  - maxnumber
    integer: maximum
  - optionsstring[]
    enum: allowed values
  - maxItemsnumber
    string_list: maximum number of entries
- nullablebooleanrequired
  Accepts null (no value)
- secretbooleanrequired
  Write-only: the value is never returned
- requiresReauthbooleanrequired
  A write needs a re-authentication in the last 10 minutes
- visibleWhenany | nullrequired
- valuestring | number | boolean | string[]required
  Effective value (string, number, boolean or list); always null for secrets
- defaultValuestring | number | boolean | string[]required
  Code default; always null for secrets
- sourcestringrequired
  - enum: "database", "environment", "default"
- secretSetbooleanrequired
  Secrets: a value is stored
- secretLast4string | nullrequired
  Secrets: last four characters
- versionnumberrequired
  Version of the database value, 0 when none
- updatedAtstring (date-time) | nullrequired
- updatedBystring (uuid) | nullrequired
- storedValueInvalidbooleanrequired
  The stored value fails the current schema; the fallback applies
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes
404setting_not_found
409setting_version_conflict

Code samples

curl -X POST "$KONNECT_API_URL/admin/settings/key/reset" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "reason",
  "expectedVersion": 1
}'

Example: request body

{
  "reason": "reason",
  "expectedVersion": 1
}

Example: 200

{
  "key": "email.transport",
  "category": "email",
  "description": "description",
  "type": {
    "kind": "string",
    "maxLength": 1,
    "min": 1,
    "max": 1,
    "options": [
      "string"
    ],
    "maxItems": 1
  },
  "nullable": true,
  "secret": true,
  "requiresReauth": true,
  "visibleWhen": {
    "key": "email.transport",
    "equals": [
      "smtp"
    ]
  },
  "value": "value",
  "defaultValue": "defaultValue",
  "source": "database",
  "secretSet": true,
  "secretLast4": "secretLast4",
  "version": 1,
  "updatedAt": "2026-10-01T09:30:00.000Z",
  "updatedBy": "updatedBy",
  "storedValueInvalid": true
}

Changes of a setting, newest first (secrets masked)

GET/admin/settings/{key}/historyDashboard session

Parameters

keystringpathrequired
cursoranyquery
nextCursor of the previous page
limitintegerquery
- max: 200
- default: 50

Responses

200
- itemsSettingChangeDto[]required
  - idstring (uuid)required
  - keystringrequired
  - versionnumberrequired
  - actionstringrequired
    - enum: "set", "reset"
  - actorUserIdstring (uuid) | nullrequired
  - reasonstringrequired
  - beforeobject | nullrequired
    { value } or, for secrets, { masked: true, set }
  - afterobject | nullrequired
  - createdAtstring (date-time)required
- nextCursorstring | nullrequired
401Not authenticated
403konnect_staff_only for anyone but konnect_admin; reauth_required on sensitive writes
404setting_not_found

Code samples

curl -X GET "$KONNECT_API_URL/admin/settings/key/history" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "items": [
    {
      "id": "id",
      "key": "key",
      "version": 1,
      "action": "set",
      "actorUserId": "actorUserId",
      "reason": "reason",
      "before": {},
      "after": {},
      "createdAt": "2026-10-01T09:30:00.000Z"
    }
  ],
  "nextCursor": "nextCursor"
}