Authentication

You'll need to authenticate your requests to access any of the endpoints in the pasby API. In this guide, we'll look at how authentication works. pasby™ offers two ways to authenticate your API requests: Basic authentication and Universal Authentication with app identities — Universal Authentication is the recommended way.

Basic authentication

With basic authentication, you must call pasby's authorisation HTTP get endpoint to retrieve a bearer token for all subsequent API calls. An authorisation request requires your organisation ID, app ID, API key, and app secret. Here's how to authenticate with cURL:

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_"

cURL "https://s.pasby.africa/api/v1/flow/ping" \
    -H "x-access-token: place-bearer-token" \
    -H "x-api-key: bk-test_"

This type of authentication only works with v1 scopes.

Please don't commit your pasby api-keys to GitHub!

Universal authentication with app identities

The recommended way to authenticate with the pasby API is by using Universal authentication. When establishing a connection using Universal Authentication with app identities, you will need your app secret — you will find it in the Developer console dashboard under API client. Here's how to add your app identity to the request header using cURL:

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

Always keep your app secrets safe and revoke it if you suspect it has been compromised.

Using an SDK

If you use one of our official SDKs, you won't have to worry about any of the above — fetch your organisation api-key and app secret from the Developer Console dashboard under API settings, and the client library will take care of the rest. All the client libraries use Universal authentication behind the scenes.