Authentication
The Finqu API uses OAuth 2.0 for authentication. This page provides reference information about the authentication implementation details.
For a complete step-by-step guide on implementing the OAuth flow, see the Authentication Guide in the Getting Started section.
Authentication Methods
The Finqu API exclusively uses OAuth 2.0 for authentication. API keys are not supported.
OAuth Endpoints Reference
Endpoint | URL | Description |
---|---|---|
Authorization | https://login.finqu.com/oauth2/authorize | Used to request user authorization |
Token | https://login.finqu.com/oauth2/access_token | Used to exchange authorization codes for access tokens |
Resource | https://login.finqu.com/oauth2/resource | Used to retrieve the merchant-specific API URL |
OAuth Flow Technical Details
For a complete walkthrough of the OAuth flow implementation, see the Authentication Guide.
Important Implementation Notes
-
After obtaining an access token, you must make a request to the resource endpoint to get the merchant-specific API URL:
GET https://login.finqu.com/oauth2/resource Authorization: Bearer YOUR_ACCESS_TOKEN
-
The merchant’s API URL is found in the
merchant.api_url
field of the response:{ "merchant": { "id": "merchant_id", "api_url": "https://merchant-name.finqu.com/api/v1", "name": "Merchant Name" } }
-
All subsequent API requests must be made to this merchant-specific API URL, not to a generic endpoint.
Access Tokens
Access tokens are sent as Bearer tokens in the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN
Token Properties
Property | Description |
---|---|
Format | JWT (JSON Web Token) |
Expiration | 1 hour (typical) |
Renewal | Via refresh token |
Token Response Example
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt-abc123...",
"scope": "products_read orders_write"
}
Scope Reference
Finqu API scopes follow the resource_permission
format. Common scopes include:
Scope | Description |
---|---|
products_read | View products and variants |
products_write | Create and modify products |
orders_read | View orders |
orders_write | Create and modify orders |
customers_read | View customer information |
customers_write | Create and modify customer data |
content_read | View content pages and blocks |
content_write | Create and modify content |
settings_read | View store settings |
settings_write | Modify store settings |
Security Best Practices
-
Keep secrets secure: Never expose your client secret in client-side code or public repositories.
-
Implement state parameter: Use a random state parameter to prevent CSRF attacks.
-
Use HTTPS: Always use secure connections for all API communication.
-
Implement PKCE: For public clients (mobile apps, SPAs), use Proof Key for Code Exchange.
-
Store tokens securely: Store access tokens and refresh tokens in secure storage.
-
Request minimal scopes: Only request the permissions your application truly needs.
-
Rotate secrets: Periodically rotate your client secret.
Common Issues
Unauthorized Errors
If you receive 401 Unauthorized errors:
- Verify your access token has not expired
- Ensure you’re using the correct token format (
Bearer YOUR_ACCESS_TOKEN
) - Check that your token has the required scopes for the endpoint
Invalid Redirect URI
If you receive an error during authorization:
- Ensure the redirect URI matches exactly what was registered with your app
- Check for trailing slashes, protocol differences (http vs https), or port numbers
Resource Endpoint Errors
If you can’t retrieve the merchant API URL:
- Verify your access token is valid
- Ensure you’re making a GET request to
https://login.finqu.com/oauth2/resource
- Check your Authorization header format