API - OAuth protocol

OAuth is the recommended authentication method for integrations between Hiboutik and third-party applications.

In practice, integrations with third-party solutions are often implemented through an application that connects to a Hiboutik account using OAuth. This provides a smoother installation process and avoids requiring the customer to manually provide API credentials.

#Why use OAuth?

OAuth provides several advantages over basic API authentication:

The customer does not need to provide their API key or webhook signature token to the third-party solution.
The application can be installed with a single click, making the onboarding process much smoother.
The customer explicitly authorizes the scopes requested by the application.
Some limitations related to the permissions of the API user are handled by OAuth.
The application can be installed by multiple Hiboutik accounts while keeping each account's access tokens separate.

For integrations intended to be installed by multiple Hiboutik customers, we therefore recommend using an OAuth application.

#How does OAuth work?

OAuth is used to issue access tokens on behalf of a Hiboutik account.

The general installation flow is:

The customer chooses to install your application.
Hiboutik displays the permissions (scopes) requested by the application.
The customer authorizes the requested scopes.
The customer is redirected to the application's configured redirect_uri.
Your application exchanges the authorization code for an OAuth access token by providing its client_id, client_secret, and the authorization code.
Hiboutik returns an access token and the authorized scopes.
Your application uses the access token to make API requests on behalf of the Hiboutik account.
Your application can then access the data allowed by the granted scopes.

The OAuth credentials belong to the application, while the resulting access and refresh tokens are associated with the Hiboutik account that installed the application.

#How do I create a Hiboutik OAuth application?

To create an OAuth application, contact Hiboutik and provide the following information:

Application name — the name that should be displayed to users.
Scopes — the permissions required by your application.
Redirect URL — the URL to which the user should be redirected after authorizing the application.
Logo — PNG in 400x400 px.

Once the application has been created, Hiboutik will provide the OAuth credentials required by your application, including the client_id and client_secret.

The client_secret must be kept confidential and must never be exposed in client-side code.

#Do I need to ask the customer for their API key?

No.

When using OAuth, the customer does not need to provide their API key to your application.

The customer simply installs your application and authorizes the requested permissions. Your application then receives an OAuth access token that can be used to access the authorized Hiboutik account.

This makes the installation process considerably simpler and avoids asking customers to copy and paste API credentials.

#Do I need to ask the customer for a webhook signature token?

No.

When webhooks are used by an OAuth application, you do not need to ask the customer for their API webhook signature token.

The webhook authentication mechanism for OAuth applications uses the application's client_id and client_secret.

This means that the application can manage its webhook authentication without requiring the customer to manually provide additional credentials.

#Access scopes

As part of the OAuth2 process, the application must specify which parts of the Hiboutik account it needs to access.

We strongly recommend requesting only the scopes that are necessary for your application to function.

An application can request the following scopes:

Scope	Access
`read_products` / `write_products`	Products, Price Rules, Product Variants, Product Categories, Product Suppliers, Product Brands, Product Tags, Product Modifiers
`read_customers` / `write_customers`	Customers, Customer Addresses, Customer Lists, Customer Tags
`read_store_credit` / `write_store_credit`	Customer Store Credit
`read_sales` / `write_sales`	Sales, Payments and Fulfillments
`read_reports` / `write_reports`	Sales Data, Z Reports, Accounting Exports, Cash Counts
`read_inventory` / `write_inventory`	Inventory Levels, Stock Orders, Stock Transfers, Inventory Counts, Inventory Reorder Points
`read_calendar_events` / `write_calendar_events`	Calendar Events
`read_time_tracking` / `write_time_tracking`	Time Tracking
`read_kitchen_screen` / `write_kitchen_screen`	Kitchen Display System
`read_settings` / `write_settings`	Users, Stores, Warehouses, Payment Types, Taxes, Resources

Scopes are separated by spaces when passed to the OAuth client.

For example:

$oauth->setScope('read_products write_products');

#What happens when a customer installs the application?

The customer is shown the permissions requested by your application before granting access.

After the customer approves the installation:

Hiboutik redirects the customer to your redirect_uri.
Your application receives the authorization result.
Your application exchanges the authorization code for an access token.
The access token is stored securely by your application.
The token is used for subsequent API requests.

Your application should store the tokens securely and associate them with the corresponding Hiboutik account.

#OAuth tokens

The OAuth access token is valid for 365 days.

The refresh token is valid for 730 days.

When the access token expires, the refresh token can be used to obtain a new access token.

If your application receives error code 1, the refresh token should be used to obtain a new access token.

Your application should therefore store both the access token and the refresh token.

#OAuth and API user permissions

With basic API authentication, API requests are made on behalf of an API user, and some operations may therefore depend on the permissions granted to that user.

OAuth applications handle some of these limitations differently because permissions are granted to the application through OAuth scopes.

One important example is webhook management.

With an OAuth application, the application natively has the ability to create webhooks. You therefore do not need to ask the customer to modify the permissions of an API user specifically to allow your integration to create webhooks.

This removes an additional configuration step during installation.

#Webhooks and OAuth applications

OAuth applications can create webhooks for the Hiboutik account that installed the application.

The customer does not need to provide an additional webhook signature token.

Webhook requests are authenticated using an HMAC-SHA256 signature based on the OAuth application's client_id and client_secret.

The signature can be generated as follows:

$timestamp = date('U');

$state_hmac = hash_hmac(
    'sha256',
    'client_id='.$webhook_app_id.'×tamp='.$timestamp,
    $my_client_secret
);

The exact values used by your application should be generated from the OAuth application's credentials.

The client_secret must remain confidential and should never be exposed in frontend or client-side code.

#How should I handle multiple Hiboutik accounts?

An OAuth application can be installed by multiple Hiboutik accounts.

Your application should therefore store OAuth tokens separately for each Hiboutik account.

The account identifier received during the application flow can be used to associate the OAuth tokens with the corresponding Hiboutik account.

For example, your database can contain one token record per Hiboutik account:

account
access_token
refresh_token
expires_in
token_type
scope

Do not share an access token between different Hiboutik accounts.

#Is there an example of a complete OAuth application?

Yes.

Hiboutik provides a complete example application with source code. It demonstrates how to build an application that uses OAuth, stores tokens, handles the OAuth client, and makes API requests.

See the HiboutikApp repository for the complete example.

The example includes:

OAuth application initialization
OAuth client configuration
Token storage
Access token handling
Refresh token handling
Application setup
API requests

#Is there an OAuth client library?

Yes.

Hiboutik provides an OAuth client library for PHP.

The Hiboutik OAuth Client demonstrates how to:

configure the OAuth client,
define the requested scopes,
generate the installation flow,
process the OAuth response,
retrieve the access token.

The client can be installed through Composer:

composer require hiboutik/oauth

Then load Composer's autoloader:

require 'vendor/autoload.php';

A basic OAuth client can then be initialized with the Hiboutik account, client ID, and client secret:

$hiboutik_oauth = new Hiboutik\OAuth\Client(
    $hiboutik_account,
    $oauth_client_id,
    $oauth_client_pass
);

Scopes can then be configured:

$hiboutik_oauth->setScope('read_products write_products');

#Complete application example

For a complete example of an OAuth-powered Hiboutik application, see the HiboutikApp project.

A typical application initializes the OAuth client and then configures the application with the access and refresh tokens:

$oauth = new Hiboutik\OAuth\Client(
    Hiboutik\Apps\DefaultApp::getAccount(),
    $client_id,
    $client_secret
);

$oauth->setScope($scope);

$app = new Hiboutik\Apps\DefaultApp();

$app->setAccessToken($access_token);
$app->setRefreshToken($refresh_token);
$app->setOAuthClient($oauth);

Once the application is initialized, API requests can be made using the OAuth access token:

$result = $app->get("/brands/", ['p' => 2]);

if ($app->request_ok) {
    print_r($result);
}

See the example application source code for the complete implementation.

¿Te ha resultado útil este artículo?