Skip to Content
APIs & ToolsREST APIAuthentication

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

EndpointURLDescription
Authorizationhttps://login.finqu.com/oauth2/authorizeUsed to request user authorization
Tokenhttps://login.finqu.com/oauth2/access_tokenUsed to exchange authorization codes for access tokens
Resourcehttps://login.finqu.com/oauth2/resourceUsed 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

  1. 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
  2. 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" } }
  3. 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

PropertyDescription
FormatJWT (JSON Web Token)
Expiration1 hour (typical)
RenewalVia 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:

ScopeDescription
products_readView products and variants
products_writeCreate and modify products
orders_readView orders
orders_writeCreate and modify orders
customers_readView customer information
customers_writeCreate and modify customer data
content_readView content pages and blocks
content_writeCreate and modify content
settings_readView store settings
settings_writeModify store settings

Security Best Practices

  1. Keep secrets secure: Never expose your client secret in client-side code or public repositories.

  2. Implement state parameter: Use a random state parameter to prevent CSRF attacks.

  3. Use HTTPS: Always use secure connections for all API communication.

  4. Implement PKCE: For public clients (mobile apps, SPAs), use Proof Key for Code Exchange.

  5. Store tokens securely: Store access tokens and refresh tokens in secure storage.

  6. Request minimal scopes: Only request the permissions your application truly needs.

  7. Rotate secrets: Periodically rotate your client secret.

Common Issues

Unauthorized Errors

If you receive 401 Unauthorized errors:

  1. Verify your access token has not expired
  2. Ensure you’re using the correct token format (Bearer YOUR_ACCESS_TOKEN)
  3. Check that your token has the required scopes for the endpoint

Invalid Redirect URI

If you receive an error during authorization:

  1. Ensure the redirect URI matches exactly what was registered with your app
  2. Check for trailing slashes, protocol differences (http vs https), or port numbers

Resource Endpoint Errors

If you can’t retrieve the merchant API URL:

  1. Verify your access token is valid
  2. Ensure you’re making a GET request to https://login.finqu.com/oauth2/resource
  3. Check your Authorization header format
Last updated on