Authentication

Authenticate your customers in real-time with informed user consent.


Overview

Authentication, or Auth for short is the first step for your users in the Okra app experience. Whether you're building a solution with direct payments or just a simple budgeting and finance management app, Auth is the gateway for informed user consent. Your users log in to their bank accounts securely via the Okra app, and through Auth, they authorise Okra to share their financial data with your application.

This enables you retrieve up-to-date account and financial data for your users, and also makes it possible to authorise payment requests through your users' accounts.

How it works

When you embed the Okra app into your application or website workflow, it guides your users through a simple authentication flow for each institution that Okra supports.

User authentication flow in the Okra app

When you users connect their accounts for the first time, the Okra API creates a record with their account information. The API also retrieves data for any of the Account data products that you set up when you build your app. When you are building a Payments product, Auth enables you to authorise instant bank-to-bank payments, and to authorise future payments from your users' bank accounts with their informed consent.

How to use

Since Auth is required for both Payment and Account data products, it is enabled by default in every app that you build, both via the App Builder, or when using the API to build with options.

Check out the Build your app guide for more guidance on creating your Okra app.

Every user's authentication flow is free of charge and will not debit your Okra Wallet.

Auth is not a paid product, because it is required to authenticate users and enable access to other products.

Account connection methods

When you build your app, you can define different authentication options for your users:

  • log in using the credentials they have on their internet banking portal, or on their banks' mobile applications, or even through manual authentication using their BVN or account numbers
  • select whether they want to connect their personal or business accounts
  • connect multiple accounts in the same app instance

These options are easy to configure when you use the App Builder. Dive into the Okra app properties to understand the different parameters you can use when you build with options.

The Okra app also helps you simplify the user flow by only displaying login methods that are supported by the banks that your user selects. Check out the Coverage guide to learn about supported account types.

Returning user experience

You can configure the Okra app to identify returning users and eliminate redundant authentication or bank selection steps in their user flows. This enables you to:

  • reduce the amount of duplicate account connections
  • collate data for the same user via different apps
  • improve user experience and reduce user friction

Check out the Returning user experience guide for more details on how this feature works.

Sample objects

These are sample requests and responses for the Get Auth by Customer operation, which returns all Auth records for a single user:

curl --request POST \
     --url https://api.okra.ng/v2/auth/getByCustomer \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "customer": "1fb1c2767c35c767741805c6",
  "page": "1",
  "limit": "10"
}
'
{
	"status":"success",
	"message":"Auth retrieved successfully",
	"data":{
		"pagination":{
			"totalDocs":36059,
			"limit":10,
			"hasPrevPage":false,
			"hasNextPage":true,
			"page":1,
			"totalPages":3606,
			"pagingCounter":1,
			"prevPage":null,
			"nextPage":2
		},
		"auths":[
			{
				"_id":"1fb1c2799642c88a20cbb9b0",
				"record":"1fb1c2707c35c767741805bf",
				"__v":0,
				"bank":{
					"name":"Unity Bank",
					"colors":{
						"primary":"#253D51",
						"accent":"#7AB702",
						"bg":"#2E465A",
						"button":"#7AB702"
					},
					"logo":"https://okra-images.s3.eu-west-3.amazonaws.com/Unity+Bank.svg",
					"icon":"https://okra-images.s3.eu-west-3.amazonaws.com/Unity+Bank+Color.svg",
					"status":"healthy",
					"v2_icon":"...",
					"v2_logo":"..."
				},
				"created_at":"2023-11-16T00:06:16.983Z",
				"customer":{
					"_id":"1fb1c2767c35c767741805c6",
					"name":"Peter Jones"
				},
				"env":"production",
				"last_updated":"2023-03-16T12:16:41.280Z",
				"owner":"1da6358130a943486f33dced",
				"validated":true,
				"current_project":"1ff62b99aea7a57a5c3baa01",
				"projects":[
					"1ff62b99aea7a57a5c3baa01"
				],
				"id":"1fb1c2799642c88a20cbb9b0"
			},
			{
				"_id":"106df5f68ded3baeae06237a",
				"record":"106df5d71705861c27f1963b",
				"__v":0,
				"bank":{
					"name":"Unity Bank",
					"colors":{
						"primary":"#253D51",
						"accent":"#7AB702",
						"bg":"#2E465A",
						"button":"#7AB702"
					},
					"logo":"https://okra-images.s3.eu-west-3.amazonaws.com/Unity+Bank.svg",
					"icon":"https://okra-images.s3.eu-west-3.amazonaws.com/Unity+Bank+Color.svg",
					"status":"healthy",
					"v2_icon":"...",
					"v2_logo":"..."
				},
				"created_at":"2023-04-07T18:12:06.234Z",
				"current_project":"1ff62b99aea7a57a5c3baa01",
				"customer":{
					"_id":"1fb1c2767c35c767741805c6",
					"name":"Peter Jones"
				},
				"env":"production",
				"last_updated":"2023-04-07T18:12:06.234Z",
				"owner":"1da6358130a943486f33dced",
				"projects":[
					"1ff62b99aea7a57a5c3baa01"
				],
				"validated":true,
				"id":"106df5f68ded3baeae06237a"
			}
		]
	}
}

Visit the API reference for a complete list of operations and sample responses.

Was this page helpful?