Flows

Flows are an integral part of performing actions with pasby™-API integrations. The very reason pasby™ exists is so every action is smooth, simple and recognisable. On this page we will delve into the different flow scopes you can use to access and manage pasby™ actions. We'll look at how to authorize,

The flow model

The flow model contains all the information about any pasby™ flow initiated by your application, such as the flow reference, mode, session states, requestee, and data claims, if any. It also contains an e-signature of a pasby user if a flow has been treated successfully; you use this to verify the authenticity of any user flow via pasby™.

Properties

Name
reference
Type
string
Description
Unique identifier for this flow.
Name
requester
Type
string
Description
Developer organisation ID otherwise known as consumer.
Name
requestee
Type
string
Description
The national identity number of pasby™ user
Name
mode
Type
string
Description
e-ID mode of flow. pasby™ supports: identification and signature.
Name
cancelled
Type
boolean
Description
Informs if flow has been cancelled
Name
onsession
Type
boolean
Description
Informs if flow has been picked up by a pasby device.
Name
iat
Type
number
Description
Timestamp of request creation in unix format.
Name
claims
Type
Record<string, dynamic>
Description
Any approved data claims from an identification mode flow.
Name
signature
Type
string
Description
pasby™-users' e-signature.
Name
signedAt
Type
number
Description
Timestamp of when flow was treated.

GET/v1/flow/authorize

Authorize your client [v1]

This endpoint only operates under v1 scopes, and is no longer supported in v2 scopes. It allows you to authenticate your client before calling other pasby™-API endpoints.

Request

GET

/v1/flow/authorize

cURL "https://s.pasby.africa/api/v1/flow/authorize?sub={org_id}&app={app_id}" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_"

Response

{
  "status": "successful",
  "reason": "Token generated successfully",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJiY25fYzI0MzFlNjYtYTdkNy00MDZmLThjMjgtNzE1YzlkYzcyOGUzIiwiYXBwIjoiYXBwXzAzYzY5YzUwLTdhNGEtNWJhYS1iYTgyLWFhODEwODRhMTQ5ZSIsInNlY3JldCI6InNuYl9hZTI0ZWRiMC02MWQ4LTExZWUtYTExMS0wMTcyYWU0NDczNGUiLCJpYXQiOjE3MTY4MjY1NzUsIm5hbWUiOiJCaXZyYSIsImV4cCI6MTcxNjgyNzE3NX0.Kow4i1A_sBwP47jPwjhaybjvOj1wzyTeMyxZw0s28iI"
  }
}

After retrieving a bearer token from this response, you must provide this in the header of your future requests to pasby™-API endpoints.

GET

Authorize your client [v2]

pasby™ v2 API scopes do not support a standalone Authorization endpoint. From this point onward all api requests are authorized using a Universal Authentication mechanism.

POST/{version}/flow/ping

Ping

Using flow:ping, you can check on changes to flows originating from your app.

Request

POST

/v1/flow/ping

cURL "https://s.pasby.africa/api/v1/flow/ping" \
-H "x-access-token: {bearer-token}" \
-H "x-api-key: bk-test_" \
-d "{"request": "req_"}"

Request

POST

/v2/flow/ping

cURL "https://s.pasby.africa/api/v2/flow/ping" \
-H "x-api-key: bk-test_" \
-H "x-access-secret: snb_" \
-d "{"request": "req_"}"

Response

Uncompleted flow

{
  "status": "successful",
  "reason": "Ping successful",
  "data": {
    "request": {
      "reference": "req_",
      "requester": "bcn_xxxxxxxxxxxx",
      "requestee": "xxxxxxxxx10",
      "iat": 1716820052,
      "mode": "...",
      "cancelled": false,
      "onsession": true,
      // ....
    }
  },
  // ...
}

Response

Completed identification flow

{
  "status": "successful",
  "reason": "Ping successful",
  "data": {
    "request": {
      "reference": "req_",
      "requester": "bcn_xxxxxxxxxxxx",
      "requestee": "xxxxxxxxx10",
      "iat": 1716820052,
      "mode": "identification",
      "cancelled": false,
      "onsession": false,
      "signedAt": 1716820121,
      "signature": "yrSTAyBrX3z+7E9NbM6SC8KCXFJqsvxdMWjC+qT7LXMrkquoZHfRC0WySRj2bbobj8uKXD1F1CvCUFWJBVJwrAiC/FqPVYK8Ea5WPb9dEFG/U6G5xyGNcw1RFU7NJMiYUdXsEmNlXgCLoUAx9JFyhFQo9pmq7eLIO5DzZ0jKRmqGhku34Y645faKwUdzUt47uRLRzmYOmDD02Gu+qCwuxTcHOHaa3FM9i4fzD218XC6E4LiwFo2kxd26Ji9fLjFWgGyeZ5CN2Fc/yl7HHWW6D2OdC1SEkPmMA/pDCDgso10DFdr9NjcCBlBCbDeP1dPMi0TwjT4C25kUxljL5C/QNw==",
      "claims": {
            "bio": {
                "birthnumber": "B/UlX5WooxYB+kTwBz4EQz621lG8J+oNdrDqtdN/e2fCpwyeg1Mdqug3YuYdvsTlQV1Smyb81dE3qtyvP4qWJTm3yevhddmO/OvX2BjWiSzHBCDSNlFvbR62d0iTSeg/6QMHtqW/f16qR36g8OYeqG3NwC7tQNnhyXMz0AYPsXK/YIInqGp+XnQF3ehulkBpSZeQutX2XXPuvlCdcWUb03JTAOdcen/w1ZefDiYjclz1NMtR2jTHrPt6UsSoCL+AZGr6T7JCOM4DvAXEwUtcjH4dALdzbZ8CJBsNk88naL7pQAUnKy+IvaO/GAE1H4VQalqrESTURDUgMLjUlTDdhMFKhIhIsAwNp+xIYPWutznEx1ESkcMlFuRdUrLXcVVBWN8KiP0XD6fK0YQAHoU90rhFuhX3pt3JH0ZID33/SLy8+O6KKsrI92d3GYJ2HwlOHC7WvgZJS+As4IS+uolFZUpv3rxi5mlR+NqQFmrNlH9J+opJvFxz61BaXjlbF/KDH4IWM1QNjGh7lDuxNyWf84kL6nffK38sKj4W2gBqwy1cHYe2yKR3yq0K3HXtdJHS3WIyz0qfbM5a3dbAf85f3Gu3QwuEa+1+csqLLCueubP5CVkCuXsqlK8k4XiIZIm0HBKxId1RgXf4bKclxSd6aHsxyDXCPenzIvzTeb2nDi0=",
                "birthdate": "uL2qxrM1f3hXuT54fBhpRbj5CYrIT9ayDIzlFSrb6URQ9gxbCzx4NnL6IK/qp1SOr1KAB6J01w0gPORaebKta8d463e/WaGNv32lWEm8KH0rFkq/POnftmsTNCNMOfXiH7efhBodMmuq1dG6I6QwnbWO0VN9W+4I1vEd69cZNADplyTbYHPV/+nnWJaB0pmeFbkZRnv6qEoOQ4u7aJrj+gULDFXpKlVjSF5aHCTGf0Z4tPe7LXfe8rQvqv6xHWtGtZfDjrLIt2hJh60NqDlF9y0bXIqqekFk/We31kgS8BZXMY6thSNtDQZUnGETpUBwitQIEYkLOw770rE6vb6v8w7AJgHQaoCNNZEJXPMhQEK3KzRPc1s1VdJcnmyiPRnnhN60VcKml/jtzs9UbkHNhRbIIDrh2VRADGnfM+oxKYIlaepaDgzJ7UOeBMa8tP+7xPG3eNP4kzuA0WyJrg0aQPZMzV6Ea46JQkgKBLlcJJ6U+DRrJqNCTbr0g0RAJX+wdk0vXg3QXaDDLxZMKm3DIQOmoLKik3zx+GQhYWt5q/fgpwZ4b1xPi7GnfZIfJgHjJtj4BhPIv1hK6bdwQ/VKa27zVetWkVbpwkT675sXguwTUMNW+5xKj7UxKsOVh3aw+8wG2J5dF3gnn0h0wzvvZsvWYs/f+hA7EWLiysk/s28=",
                "gender": "MDDZdWxdb2j4Jpp4U1zf8GMuc2pXxYn5HhH+RQF3n7q9DlMOkzddFXCizsAikNEjIm2X5N0J8k3L/ZAw5tJzX1mrMUq9YrPYi0S46CT/y5Z1v9aPwkJKkxZ7mFu5qDGiI4yukIDLK6P6JQRzE9IcEjocndNEQbFZk9azcNVNcrB47/26/4kMdqi2PLFKh3Y3S8cvo1+L1P96uvUvxAj3gWTE7LojWgAoJ2KMLSR+F506jDy3Xv1E9IItxAN9O4B29Thy76ZSV10//+wWCIysiDT8/2UeV+LlFscWiu8xQhgLvBABs2QGH+SMnLPptTeMOsP6CC4t3XBzen26ffIaBNRNnM0LeN0IMQ6VUKUn1A9nJHislIedw3VO/pL2Vbc1wh+/TN/RfwchfUimn3zVc+J0xBDtiZnEDB02fkjVTLtfhzobbE4qv6caookx83yIIHdo0U7dPF53EE+smmnMabD3YA3i/w4t77KYpXiG1JhWR5rQ+sA+I45Pv0NhPuEwY39JV5s4CVjQmPDVfxeN1LBjN2Pul7QWCL1Nqx8TMJgMgED3p+VJC8jLWRW9yJh9U0DRXkAVLKzh3z/O3US80GnzEOxeKIZqvTpN8GHYUrOT/19mxmCl37Bp+Bjaq34LK19rbKlyAfhIHVCSMcAKh29IIT2ZYmtE/fgaeUZRkT0="
            },
            "contact": {
                "email": "y6l/srG+g/2l2QinsjXxnn4MxY0cTzIDFiRrChjtSIl/LUUkQt8zAUsY4UIPHJDb+LvMH8LHN6LWZ8HNZ+Y3L36Dwy3KdwWSheDrWsXskxVfl5gHGnPl/lvQjyWuxcfwAlH161oJZwKpLhGsVJ8UkI7mm/l+jKznhio+VRsaKcJexky92hE+0rkpsQfWKd25WV53hlXM9n8PQJHzkUOzZwpel3YYo/YPU8hhWaHkFJjY3qnzs9qE+qLQ6RazrwHZz9NtIOYOtajLumQ7QLlrsc3CyCEucPUfNmj/WAWSuikDTegDJmOMElt0Sqf7SsIOGT/Eewd0B+uPxuXtJPR0+ZmHF69IzrtlSSMtVYY5wZt5vjVCrbw9mhVkdkanGKrh3KyjHJE8m6rfNscYUy8768YJvA36FIvzWfk89aknKSaf2L+gLc9BM9zxAtPM5Qcz3K6D8zi2qKdcxZBCoqEvEZYltOsHE8TMRug3HfdEaihVr8VTGwBiNE7ii1D0XRxR36WdEymriy499DkXBri6rRPQxS0rRDr4RqJV0+7rlcmLxYUjvq/ii/ONGiZFtfw0zDtz42PqKyokUQOxZqVAdTc8SvrPoBk/bVpo7gvZUXfYSxG+5e3HqEixQKuCXHSeJH9tCgHilXJV2DaLgqx10TVJcW2NnaOOvIBbUNs2NSQ="
            },
            "naming": {
                "family": "SsF83HO/6g6+Sf+6n0nl3NhSJoEsMYYy5KMuBkIrtH33pD+LanPTUlYcZSYtgOpYV2ozq8kEE7kYalsyh/Kg/JzRCVO35N/KLuwddVZAgkW1AmWpzjEa3yssCTI1HPSG6VFRuV+ITEq1tGnuNzbncRkTbfwdQbGDO4M7oYKg3o7z67Hv4lXWhKc1cDqee95Ja/JRmbsVqSssJbnNUgMxvCyWJQej2ALN1J4lhPsy+WWWX2l6ANsbCsKQMQcQeGQwPfCabiSBazZv2YxRL5CN/gaIpIvjNvBglnJoc2qFPSKzk5VNeJkpXQNvd3HY0O/5ZxzfHR7y/ZUqkyBB9TJc2XsANGtzbrmHnJy7fq6W0ixxJQDeGo3qfsZmoaUb9967RIQ/DRG9To1CbWw1KXDqSbwvaYfOCxR0kXLJKRzV/QNBRzAq8XTe6XgHBGEfkkJR7/dG7Cpt1Jf9tm1PdkRsMYQoNFPhHjAGRbLGsLYcawK1BgqOXM9JMpSZKizGxF6MvfIe4ovC2TS6Y+cWXdUDTFURdSvvY4D+bjAryiCkPYybAFjR1okLINdei0/KyfJXz4qYiZQd4tp+PAd7wi26fABwDeBA8NDFZOYB01P9ACT2pgHGoDIVopf8l2n5cEztKYkIze3PHgvhmGWZP7cz+3paX4kcIr8sg+Q2VVlOm4g=",
                "given": "LqDr6DjnleWbPLESTCd8t9ttuwFL4fwiW1R3hS5Q/o/jk/7K8E1P2Kup2iSuVWwriQ9KLwpzUMhcs7rnDhChUZyJXyh1d2VNzgbTDRNaW2h0/1OHJLnQs6s+hsW5kFrfDyt2KPEHvn1vMVIaEdDSzLmtQC2JQjiFvcVw8oub/CQedXCYWsuui1A8GTef+0EGD78tz46iFEt1hJcijE4CdKTGuH8Ph7nd3rwSpg4APLVcU82ywx4sJkkz3Ym2Vk0Yk2yaDL8WBLqMWHh9jNMvpKgwA9RiocDP6ci8s/Elm2WNE+GspFYur7moEn04NVQvkZbDaKRXKU7FrPvtwX/Me8C2gv4/FnevNas4EOsx8rxhPvmWD20U1o9TCUHzecJg5AJMQ4Y4t90jjaINQ7f7IMIZZJ3RR5M2zs9uq2UdMcW0C2MCjqe9aydWs4WqkFeu2YoWlNoOs3FPVpP2OzAs77MDcnf/dltywz3LZMXrt62ZRCaVIIA1aj/tNewT9NBbrBYnaFzfpaHVOWaWFEyLrmTI1nb0k7pB7o3OAyRYoOCwQhJ6ox5L8PxVaJyjAADZxLkym76E4y6kCEHMe6xaM7L+BBuYhVg4TgOzxH/5b/A3q7ZAKzf9g3Pvm13JZMvsOJr9gUc+bnx7ZsNNrjjeTX4P9riDipU5fR250yT6/N8=",
                "middle": "oOEiLU4qtc2R7j5HrYjMth3wcqOEXHkWwhFvf+nUEMLi1wgSChJVRLS8D29FNwTj+extNB/i9l4tCRbH3SsKO7X2pGIkD+0TXF2ja1Qr1hC0owiVdHa+KE+HjWbb1BjJT+cIVF8crOdKlMIrXRlkJC5Mqd+IYqpBpokIqku9In09utJ/WS1KxZEWP8nZT16FTW6yITZ08nYjj3FOMkxkf8eyfugPeS6yHPXMcQolKdsgKapuPoyYYM1G75NYn9OBU0B+iPjAgoGNO8d2mbpc6gYuM1TPQtrVHYv+N6bk1xSzA+xSePU1B2vEAtF82GHitKywdZDfO0mdH7A1sF2S49yzY1YdWCkBnuW5p9RxBhzGMfUu6D90/OiDNXt2KjWF7vJGq+bGPNhWXnmkFAytviyZ2oxI3NJNpHuFsWLq8Ha4VCNM4hRcwHuFWXU+Af8YQEnprpGBIT1VFE4jISUWd9zzrCRRSbz6RRHewrGoodyeAf12ikBBRTIM+mv0TnCIqpT1kp4tYA8MC+zad7U2dlQNRe1YmsTRNCsUf6HYKgHz4EQSqAgr/dc8Kz/FvuKyFbBI2rE2z5qitCB72VyqpRFMSrqZD5fKj0f4mrY6hOkSYpzvzvv0+xNGmro97wwwcd7KMkZBojS0UyuCOYwlwr8kTHrX5eb8mzZYErTrFiM="
            },
            "nationality": {
                "residence": "q8nNX15Gszw7fvEIb0oHV33zk34Up8cWppN+uyM3mvsIGf3nNw/Qh+YkB6rL4lfC18Gr0+gY45Cd9g4zpujLjxuNP6fLDdhGE7kB/35GlAFrWT8ZUw8JSthSaomnh81aY7gfcOCMAkWHaD1jHsd6rGsh1dbVVm4Q3zz4A6hFW7i3bf604XBx64AfRgmxuh2+ocmXa+hE6WIz0ZV8su4whuUdOUZ0Q1fEovcO+znIOYNJL1QqLHBs5boOockOteL9YQO5bKgJYrY96+TnpZTHmHaY7VKMiusTqy8/tY2jxaj/9qD7hbgp2LD8Nht1ttwz7f6BIizSWqk0bTVYW3Upx8/DiERGLXlOTBVYqlefXAZZn6LqAV5npH4W0hxdZv8hwPiDy2HTRwP89jume4fHtEBu4RDZlfy1A/Xkkrur0KSqSxTYS0x2OQdP/1lLeiwngcwX7EAQGHqsuCSwMrM0a7MNKoxOA4WjYoz69dZNL70u98rToDz8rf3pD76rlbgEb64Q60DUkRoUAMESdvzxQgPk/5PVsoNO00wPXsIUiErKfUSbGb30aGm9hKhJKwNYChlSnyX1oUruibjJpECfKOnDRkv1zZteRsitA0BJ2fbh2FqWGWyhyuSBDobEBNp486w90iGaFnKritoflB+DQiFXYZP428ZjD6iKz7ymMuY=",
                "primary": "yAws7biU75sacmW8uTPnqm/Zq5UmDsgQhLePufO1+kqA1Ag54T8lLEejKtR1/vTXBfBANX86NlsPwnBOBLeEMwxe5uo4LTA20NWh+9W2sTCd1DTHAYmCLI+CwIfgHjvu5qH8EmNsYXmBLFbtLStZBkk3wytiidV+Ys32110x5/W41hXE6c5y5aHCeDdWwh3byUBGL3UQj4ktRU8GQbIfziuL237xinvQUJHnQT01x7WzYTdcnG3hu8A/s5kYT6hX7TbafWfbJXqj+XyIrAFq2/StZMVm8eV2uJ75DUsZD0t0MB/PulZuUDNAsY76VBoCE9+BKJQhV6+Fu7gofpsjHQP3flnBPSsjswonHEX2Otvz2fjxdmlK1jfjO1qWptYLvokIJGgpITgM78xas6+Hre4Ai9JVjljyUQiwKVO6XLAede0g0bUOhcBs18N/wpX8+zx4d4GMRozCgHFaZKne8TSSjb0nsVtwkhM17vkvw5ocPwE9/xNysg+yyC0EEABtuehIlrAdgpShAwt5wY2dTtmvfQOnFpO3Nj2TgdQdyAKW7GaZx/dZrangdioWq9RkaE9aqDulOcBrGkHIUR+NivZSe800xhGZ3eI2Sdw6lp8XzLVI8tQ9Iccn2GzYz3exgv4ONZblcxbCpEKao4q9t/7o7STZMk9t/cI1pcwZWQE="
            }
        },
      // ....
    }
  },
  // ...
}

In the completed identification flow response, you must have realised that the claims returned a weird, long string. All sensitive ID data points consented to by pasby™ users are encrypted with the RSA keys of the app they are currently interfacing with. As a consumer, you will need to use your private keys to decrypt these claims before you can interpret the details.

pasby™ issues unique keys to both organisations and their individual apps on the first generation. You can grab your keys from the service account files on the Developer Console.

POST/v1/flow/polling

Polling

Polling alike ping except it follows the HTTP Long polling logic. Using flow:poll, you can check on changes to flows originating from your app.

Request

POST

/v1/flow/polling

cURL "https://s.pasby.africa/api/v1/flow/polling" \
-H "x-access-secret: snb_" \
-H "x-api-key: bk-test_"
-d "{"request": "req_"}"

pasby™ only supports a v1 endpoint for flow:poll scopes. The flow:poll response is the same as flow:ping.

POST/{version}/flow/cancel

Cancel

The scope flow:cancel is used to terminate any flow originating from your app. It also affects flows already in session; in such cases, the action will be rendered void.

Request

POST

/v1/flow/cancel

cURL "https://s.pasby.africa/api/v1/flow/cancel" \
-H "x-access-token: {bearer-token}" \
-H "x-api-key: bk-test_" \
-d "{"request": "req_"}"

Request

POST

/v2/flow/cancel

cURL "https://s.pasby.africa/api/v2/flow/cancel" \
-H "x-api-key: bk-test_" \
-H "x-access-secret: snb_" \
-d "{"request": "req_"}"

Response

{
  "status": "successful",
  "reason": "Request now cancelled",
  "data": {
    "model": {
      "id": "req_",
      "consumer": "bcn_•••••••",
      "app": "app_•••••••",
      "mode": "identification",
      "action": "login",
      "payload": "A simple payload used during describing identification flow intent",
      "iat": 1707028058,
      "exp": 1707028418,
      "user": "bid_•••••••",
      "ip": "•••••••",
      "name": "My app name",
      "acquireClaims": [
        "naming.family",
        "naming.given",
        // ...
      ],
      // ...
    }
  },
  // ....
}

request: (string) The reference ID of such flow you'd wish to terminate.

The request body should be in a raw format with a JSON object.