Backend Integration

Expose your user store to the auth API

Build an api within your product that exposes your user store to return a single user based on a specified search term.

Phone number lookup

This term should be how you expect your users to login via phone number. https://yourproduct.hubtel.com/api/userstore/0245936308

The success response from your endpoint should look like:

    {
      "message": "Success",
      "code": "200", // Code should be string and not a number
      "data": {
        "mobileNumber": "233456789023",
        "email": "[email protected]",
        "tokenData": {
          "some-property": "fbed9979-4ed0-4f26-a7f3-73e29315ae4c",
          "additional-property": "corresponding -data"
        }
      }
    }

your response should strictly follow this format. Any extra data you want to include as part of your token can be added via the tokenData property.

Email lookup

This term should be how you expect your users to login via email. https://yourproduct.hubtel.com/api/userstore/[EMAIL]

The success response from your endpoint should look like:

    {
      "message": "Success",
      "code": "200", // Code should be string and not a number
      "data": {
        "mobileNumber": "233456789023",
        "email": "[email protected]",
        "tokenData": {
          "some-property": "fbed9979-4ed0-4f26-a7f3-73e29315ae4c",
          "additional-property": "corresponding -data"
        }
      }
    }

your response should strictly follow this format. Any extra data you want to include as part of your token can be added via the tokenData property.

Response description:

Property	Type	Description
message	String	A string that indicates the status of the request.
code	String	A string that represents the HTTP status code.
data	Object	An object that contains the response data.
mobileNumber	String	A string that represents the user's mobile number.
email	String	A string that represents the user's email address.
tokenData	Object	An object containing additional data to be included in the token. All properties of this object must be strings.

Other responses you can send include:

• BadRequest (Code: 400): If the API call fails due to a bad request.

• NotFound (Code: 404): If the API call fails as the phone number is not found

• Forbidden(Code: 403): If the account lookup is not allowed due to permissions,return a custom response with the code "403" and an appropriate message.

Contact the BackOffice

The next step in getting your application to work with the Centralized Hubtel Authentication is to have it registered with with the hubtel back office. The required data for registration should be:

Key	Sample	Description
productName	"Sample Product"	Name of your product. e.g. RaiseUp
productLogo	"logo_url"	The URL of your product logo
appName	"Sample App"	Name of your application. e.g. RaiseUp Mobile
accountLookUpUrl	"lookup_url"	The URL to your account lookup page
primary	"color_code"	The primary color of your application
senderId	"Hubtel"	The SMS sender ID of your application
bgLight	"bg_color_code"	Background light color code
hoverState	"hover_state"	The hover state of your application
validityPeriod	30.0	Validity period of your token in days

{
  "productName": "Sample Product",
  "productLogo": "logo_url",
  "appName": "Sample App",
  "accountLookUpUrl": "https://yourproduct.hubtel.com/api/userstore/0245936308",
  "primary": "color_code",
  "senderId": "sender_id",
  "bgLight": "bg_color_code",
  "hoverState": "hover_state",
  "signingKey": "signing_key",
  "validityPeriod": 30.0 //validity period of your token in days
}

After a successful registration you should get the payload below as response:

200 Response:

{
  "productName": "Sample Product",
  "productLogo": "https://example.com/sample-logo.png",
  "appName": "Sample Application",
  "accountLookUpUrl": "https://example.com/account-lookup",
  "id": "3f29bc6f-a7a6-405b-8b80-b4159063639f",
  "primary": "#00FF00",
  "senderId": "SampleSenderId",
  "bgLight": "#FFFFFF",
  "hoverState": "#005500",
  "signingKey": "SampleSigningKey",
  "isActive": true,
  "validityPeriod": 3600
}

The Id property "Id": "3f29bc6f-a7a6-405b-8b80-b4159063639f" in the response should be preserved as it will be required for the front end integration.

Was this page helpful?

Happy React is loading...