Skip to content
konnect
Français

Development environment: content is being written, nothing points to production.

Documentation contents

auth

Version 0.1.010 operations

Log in with email and password (and TOTP when enabled); sets the session cookie

POST/auth/login

401 invalid_credentials, 403 totp_required when 2FA is on and the code is missing or wrong, 429 too_many_attempts.

Parameters

No parameters.

Request body application/json

  • emailstringrequired
  • passwordstring (password)required
  • totpstring

    Six digit TOTP code, required when 2FA is enabled

Responses

  • 200

    • userUserDtorequired
      • idstring (uuid)required
      • emailstringrequired
      • firstNamestringrequired
      • lastNamestringrequired
      • phonestring | nullrequired
      • platformRolestringrequired
        • enum: "merchant", "konnect_admin", "konnect_support", "konnect_compliance"
      • totpEnabledbooleanrequired
    • membershipsMembershipSummaryDto[]required
      • organisationIdstring (uuid)required
      • organisationNamestringrequired
      • roleIdstring (uuid)required
      • rolestring | nullrequired

        Predefined role key, null for a custom role

      • roleNamestringrequired
      • isOwnerbooleanrequired
      • permissionsstring[]required
      • scopestringrequired
        • enum: "all", "accounts"
      • accountIdsstring[]required

        Payment account ids when scope is "accounts"

Code samples

curl -X POST "$KONNECT_API_URL/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "demo@konnect.test",
  "password": "password",
  "totp": "totp"
}'

Example: request body

{
  "email": "demo@konnect.test",
  "password": "password",
  "totp": "totp"
}

Example: 200

{
  "user": {
    "id": "id",
    "email": "buyer@example.com",
    "firstName": "Salma",
    "lastName": "Example",
    "phone": "phone",
    "platformRole": "merchant",
    "totpEnabled": true
  },
  "memberships": [
    {
      "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
      "organisationName": "organisationName",
      "roleId": "roleId",
      "role": "role",
      "roleName": "roleName",
      "isOwner": true,
      "permissions": [
        "payments.view"
      ],
      "scope": "all",
      "accountIds": [
        "string"
      ]
    }
  ]
}

End the current session and clear the cookie

POST/auth/logoutDashboard session

Parameters

No parameters.

Responses

  • 204

Code samples

curl -X POST "$KONNECT_API_URL/auth/logout" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Current user and memberships with role, permissions and scope

GET/auth/meDashboard session

Parameters

No parameters.

Responses

  • 200

    • userUserDtorequired
      • idstring (uuid)required
      • emailstringrequired
      • firstNamestringrequired
      • lastNamestringrequired
      • phonestring | nullrequired
      • platformRolestringrequired
        • enum: "merchant", "konnect_admin", "konnect_support", "konnect_compliance"
      • totpEnabledbooleanrequired
    • membershipsMembershipSummaryDto[]required
      • organisationIdstring (uuid)required
      • organisationNamestringrequired
      • roleIdstring (uuid)required
      • rolestring | nullrequired

        Predefined role key, null for a custom role

      • roleNamestringrequired
      • isOwnerbooleanrequired
      • permissionsstring[]required
      • scopestringrequired
        • enum: "all", "accounts"
      • accountIdsstring[]required

        Payment account ids when scope is "accounts"

Code samples

curl -X GET "$KONNECT_API_URL/auth/me" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "user": {
    "id": "id",
    "email": "buyer@example.com",
    "firstName": "Salma",
    "lastName": "Example",
    "phone": "phone",
    "platformRole": "merchant",
    "totpEnabled": true
  },
  "memberships": [
    {
      "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
      "organisationName": "organisationName",
      "roleId": "roleId",
      "role": "role",
      "roleName": "roleName",
      "isOwner": true,
      "permissions": [
        "payments.view"
      ],
      "scope": "all",
      "accountIds": [
        "string"
      ]
    }
  ]
}

Re-authenticate with the password or a TOTP code; valid for 10 minutes

POST/auth/reauthDashboard session

Parameters

No parameters.

Request body application/json

  • passwordstring (password)
  • totpstring

    Six digit TOTP code

Responses

  • 200

    • reauthenticatedUntilstring (date-time)required

Code samples

curl -X POST "$KONNECT_API_URL/auth/reauth" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "password",
  "totp": "totp"
}'

Example: request body

{
  "password": "password",
  "totp": "totp"
}

Example: 200

{
  "reauthenticatedUntil": "2026-10-01T09:30:00.000Z"
}

Send a one-time password reset link (always 202, whether the email exists or not)

POST/auth/password/forgot

Parameters

No parameters.

Request body application/json

  • emailstringrequired

Responses

  • 202

Code samples

curl -X POST "$KONNECT_API_URL/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "demo@konnect.test"
}'

Example: request body

{
  "email": "demo@konnect.test"
}

Set a new password with a reset token; ends every session

POST/auth/password/reset

Parameters

No parameters.

Request body application/json

  • tokenstringrequired
  • passwordstring (password)required
    • minLength: 10

Responses

  • 204

Code samples

curl -X POST "$KONNECT_API_URL/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "token",
  "password": "password"
}'

Example: request body

{
  "token": "token",
  "password": "password"
}

Start TOTP enrolment (requires re-authentication)

POST/auth/totp/setupDashboard session

Parameters

No parameters.

Responses

  • 200

    • secretstringrequired

      Base32 secret, shown once for manual entry

    • otpauthUrlstringrequired

      otpauth:// URL for a QR code

Code samples

curl -X POST "$KONNECT_API_URL/auth/totp/setup" \
  -H "Cookie: konnect_session=$KONNECT_SESSION"

Example: 200

{
  "secret": "secret",
  "otpauthUrl": "otpauthUrl"
}

Confirm TOTP enrolment with a first code

POST/auth/totp/enableDashboard session

Parameters

No parameters.

Request body application/json

  • codestringrequired

    Six digit TOTP code

Responses

  • 204

Code samples

curl -X POST "$KONNECT_API_URL/auth/totp/enable" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "code"
}'

Example: request body

{
  "code": "code"
}

Turn TOTP off (requires re-authentication and a current code)

POST/auth/totp/disableDashboard session

Parameters

No parameters.

Request body application/json

  • codestringrequired

    Six digit TOTP code

Responses

  • 204

Code samples

curl -X POST "$KONNECT_API_URL/auth/totp/disable" \
  -H "Cookie: konnect_session=$KONNECT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "code"
}'

Example: request body

{
  "code": "code"
}

Identity of the API key used for the request

GET/auth/api-keyAPI key

Parameters

No parameters.

Responses

  • 200

    • organisationIdstring (uuid)required
    • apiKeyIdstring (uuid)required

Code samples

curl -X GET "$KONNECT_API_URL/auth/api-key" \
  -H "x-api-key: $KONNECT_API_KEY"

Example: 200

{
  "organisationId": "org_01J9Z3K4EXAMPLE0000000000",
  "apiKeyId": "apiKeyId"
}