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.

Was this page helpful?