Authentication (OAuth basics)

This guide covers the fundamentals of OAuth 2.0 authentication for the Finqu platform.

OAuth Flow

Finqu uses the standard OAuth 2.0 protocol for API authentication. This secure delegation protocol allows third-party applications to access resources on behalf of users without exposing their credentials.

OAuth Endpoints

The Finqu OAuth system uses the following endpoints:

Authorization: https://login.finqu.com/oauth2/authorize
Token: https://login.finqu.com/oauth2/access_token
Resource: https://login.finqu.com/oauth2/resource

Step-by-Step Authentication Flow

Request Authorization

Redirect the user to the authorization endpoint:


https://login.finqu.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=products_read orders_write&
  state=RANDOM_STATE_STRING

Receive Authorization Code

After the user approves, they’ll be redirected to your redirect URI with an authorization code:
```
https://your-redirect-uri?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING
```

Exchange Code for Access Token

Make a POST request to the token endpoint:


POST https://login.finqu.com/oauth2/access_token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET&
redirect_uri=YOUR_REDIRECT_URI

Retrieve API URL & User Information

After receiving the access token, make a GET request to the resource endpoint to retrieve the merchant-specific information:


GET https://login.finqu.com/oauth2/resource
Authorization: Bearer YOUR_ACCESS_TOKEN

The response will contain user and merchant information including API endpoints:


{
  "id": "user_id",
  "username": "user@example.com",
  "name": "User Full Name",
  "merchant": {
    "id": "merchant_id",
    "name": "Merchant Name",
    "endpoints": {
      "admin": "https://merchant-name.myfinqu.com",
      "api": "https://merchant-name.api.myfinqu.com"
    }
  },
  "merchant_name": "Merchant Name",
  "admin_endpoint": "https://merchant-name.myfinqu.com",
  "api_endpoint": "https://merchant-name.api.myfinqu.com"
}

Note

The response includes both nested (merchant.endpoints.api) and top-level (api_endpoint) formats for backward compatibility. We recommend using the nested format for new implementations.

Make API Requests

Use the access token and the merchant-specific API URL for your API requests:


GET https://merchant-name.api.myfinqu.com/3.0/products
Authorization: Bearer YOUR_ACCESS_TOKEN

Getting Access Tokens

Access tokens are obtained through the OAuth flow described above. Once you have an access token:

It must be included in the Authorization header as a Bearer token
Has a lifespan of 6 months
Can be refreshed using a refresh token (valid for 2 years)

Using Refresh Tokens

When your access token expires, you can use the refresh token to obtain a new one without requiring the user to re-authenticate:


POST https://login.finqu.com/oauth2/access_token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=YOUR_REFRESH_TOKEN&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Understanding Scopes

Finqu API uses scopes to control access to different parts of the API. Scopes follow the format of resource_permission:

_read scopes grant read-only access (e.g., products_read)
_write scopes grant write access (e.g., products_write)

Available Scopes

Below is the complete list of available scopes in the Finqu platform:

Analytics

analytics_read - View analytics data
analytics_write - Create and modify analytics configurations

Catalog

catalog_read - Access catalog information
catalog_write - Modify catalog structure and settings

Checkouts

checkouts_read - View checkout information
checkouts_write - Create and modify checkouts

Customers

customers_read - Access customer information
customers_write - Create and modify customer data

Discounts

discounts_read - View discount information
discounts_write - Create and modify discount codes and rules

Domains

domains_read - View domain settings
domains_write - Manage domain configurations

Emails

emails_read - View email templates
emails_write - Modify email templates and settings

Feeds

feeds_read - Access product feeds
feeds_write - Create and modify product feeds

Files

files_read - Access files and documents
files_write - Upload and manage files

Inventory

inventories_read - View inventory information
inventories_write - Update inventory levels and settings

Marketing

marketing_read - View marketing campaigns and data
marketing_write - Create and modify marketing campaigns

Media

media_read - Access media files (images, videos)
media_write - Upload and manage media files

Payment Methods

payment_methods_read - View payment method information
payment_methods_write - Configure payment methods

Point of Sale (POS)

pos_read - Access POS information
pos_write - Configure and manage POS settings

Products

products_read - View product information
products_write - Create and modify products

User Profile

profile - Access to basic user profile information

Sales Channels

sales_channel_read - View sales channel information
sales_channel_write - Configure and manage sales channels

Sales

sales_read - Access sales data and orders
sales_write - Create and modify orders

Settings

settings_read - View store settings
settings_write - Modify store configuration

Shipping Methods

shipping_methods_read - View shipping method information
shipping_methods_write - Configure shipping methods

Staff

staff_read - View staff information
staff_write - Manage staff members and permissions

Themes

themes_read - Access theme data
themes_write - Create and modify themes
themes_extend_read - Access theme extension data
themes_extend_write - Create and modify theme extensions

Success AI

success_agent_read - Access Success AI agent data
success_agent_write - Configure Success AI agents

Partner

partner:themes_read - Access partner theme data
partner:themes_write - Create and modify partner themes
partner:apps_read - Access partner app data
partner:apps_write - Create and modify partner apps

Requesting Scopes

When requesting authorization, include the scopes your application needs as a space-separated list in the scope parameter:


https://login.finqu.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=products_read orders_write customers_read&
  state=RANDOM_STATE_STRING

Always follow the principle of least privilege by requesting only the scopes your application actually needs. Users will see all requested scopes during the authorization process and may decline if too many permissions are requested.

Best Practices

Store credentials securely: Never expose your client secret in client-side code
Validate state parameter: Always verify the returned state matches your original request
Request minimal scopes: Only ask for the permissions your application needs
Handle token expiration: Implement proper error handling for expired tokens
Use HTTPS: Always use secure connections for all API communication
Implement PKCE: For public clients, use Proof Key for Code Exchange to enhance security