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