User Approvals

The Karrier Number system can be used to verify a user approves an action. This enables phone number based 2FA using the blockchain.

User approvals offer secure methods for verifying wallet or address ownership. There are two primary approaches:

• Signature Verification: Verifies ownership without recording any transaction on the blockchain, thus avoiding associated gas costs.

• Event Verification: Confirms ownership through a blockchain event emitted by a contract. This method incurs a minor transaction cost and leaves an on-chain record.

In both cases, the approval flow remains consistent:

1. Generate an Approval URL 📄

2. Redirect the User to the Approval URL 👉

3. Handle the Return URL 🔧

4. Lookup the Response to Confirm Approval ✅

Example Call Using 'event' Verification

// Example Call using 'event' verification
curl --location 'https://kns-api.karrier.dev/kns/approval' \
--header 'x-api-key: testkey' \
--header 'Content-Type: application/json' \
--data '{
  "title": "SIM SWAP",
  "message": "Would you like to deactivate your previous SIM card and activate a new SIM card?",
  "phoneNumber": "[phone]",
  "successRedirectUrl": "yes/success",
  "cancelRedirectUrl": "no/failure",
  "referenceNumber": "I#23493249243932",
  "method":"event"
}'

{
    "approvalUrl": "https://dashboard.karrier.dev/kns-approve?ref=ea24b697d2730d82c755a5b7",
    "approvalNumber": "ea24b697d2730d82c755a5b7"
}

post

Authorizations

x-api-keystringRequired

Body

titlestring · string · min: 1 · max: 255Required

The title of the approval request.

Example: SIM Replacement Approval

messagestring · stringRequired

A description of what the approval request is for.

Example: Would you like to deactivate your previous SIM card and activate a new SIM card?

successRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user approves the request.

Example: https://example.com/approvedPattern: ^https?:\/\/.*$

cancelRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user cancels the approval request.

Example: https://example.com/cancelPattern: ^https?:\/\/.*$

referenceNumberstring · string · min: 1 · max: 255Required

The reference number for the approval request.

Example: SIM-1234

methodstring · enumRequired

The method to use for the approval request. This can be either "sign" or "event".

Example: signPossible values:

phoneNumberstring · E.164Required

The user's phone number in E.164 format.

Example: [phone]Pattern: ^\+?[1-9]\d{5,14}$

Responses

200

Ok

application/json

approvalUrlstringOptional

approvalNumberstringOptional

errorstringOptional

400Error

application/json

post/kns/approval-phone

POST /kns/approval-phone HTTP/1.1
Host: kns-api.karrier.one
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 304

{
  "title": "SIM Replacement Approval",
  "message": "Would you like to deactivate your previous SIM card and activate a new SIM card?",
  "successRedirectUrl": "https://example.com/approved",
  "cancelRedirectUrl": "https://example.com/cancel",
  "referenceNumber": "SIM-1234",
  "method": "sign",
  "phoneNumber": "[phone]"
}

{
  "approvalUrl": "text",
  "approvalNumber": "text",
  "error": "text"
}