# 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](/get-started/authentication) 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://account.finqu.com/oauth2/authorize` | Used to request user authorization |
| Token | `https://account.finqu.com/oauth2/access_token` | Used to exchange authorization codes for access tokens |
| Resource | `https://account.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](/get-started/authentication).

### 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://account.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:

   ```json
   {
     "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

| Property | Description |
| --- | --- |
| Format | JWT (JSON Web Token) |
| Expiration | 1 hour (typical) |
| Renewal | Via refresh token |

### Token Response Example

```json
{
  "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

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://account.finqu.com/oauth2/resource`
3. Check your Authorization header format