# SuperPay Admin API — Frontend Developer Guide

This documentation explains how to integrate with the SuperPay Admin API from a frontend application. It covers authentication, store configuration, the dynamic form system, and common pitfalls.

## GraphQL Endpoint

All API operations use GraphQL at:

```
POST /graphql
```

All requests must include `Content-Type: application/json`. Authenticated requests require a `Bearer` token in the `Authorization` header (see [Authentication](./authentication.md)).

## Table of Contents

| Document | Description |
|----------|-------------|
| [Authentication](./authentication.md) | Login via email OTP code, JWT tokens, 2FA, user profile |
| [Merchant Onboarding](./merchant-onboarding.md) | Creating stores, inviting team members |
| [Store Configuration](./store-configuration.md) | Loading and saving store settings via the dynamic form system |
| [Form Actions](./form-actions.md) | Executing actions like "Test Connection" from the form UI |
| [Pitfalls & Tips](./pitfalls-and-tips.md) | Common gotchas and best practices |

## Quick Start

### 1. Authenticate

```graphql
# Step 1: Request a login code
mutation {
  requestLoginCode(requestLoginCodeInput: { email: "admin@example.com" }) {
    success
    message
  }
}

# Step 2: Verify the 6-digit code from your email
mutation {
  verifyLoginCode(verifyLoginCodeInput: { email: "admin@example.com", code: "123456" }) {
    access_token
    user {
      id
      email
      username
      twoFactorEnabled
    }
  }
}
```

Store the `access_token` and include it in all subsequent requests:

```
Authorization: Bearer <access_token>
```

### 2. Load Store Configuration Form

```graphql
mutation {
  getStoreConfigFormData(storeDomain: "my-store.myshopify.com") {
    formData
    formSection {
      ... on ConfigFieldGroup {
        machineName
        label
        fields { ...AllFields }
      }
    }
  }
}
```

This returns:
- **`formSection`** — the dynamic field definitions (what to render)
- **`formData`** — the current values (JSON string, must be parsed)

### 3. Save Changes

```graphql
mutation {
  updateStoreConfigFromForm(
    storeDomain: "my-store.myshopify.com"
    formData: { general: { domain: "my-store.myshopify.com", test_mode: true, store_name: "My Store" } }
  ) {
    formData
    formSection { ... }
  }
}
```

### 4. Test a Connection

```graphql
mutation {
  executeFormAction(executeFormActionInput: {
    storeDomain: "my-store.myshopify.com"
    sectionClassName: "PSPAdyenFormSection"
    actionCallback: "testConnection"
    formData: { apiKey: "AQE...", merchantAccount: "MyMerchant" }
  }) {
    success
    message
  }
}
```

### 5. Autofill Integration Credentials (God Users Only)

Use this query to fetch test credentials for a specific integration, so the frontend can prefill integration forms.

```graphql
query GetIntegrationTestCredentials(
  $category: IntegrationCategory!
  $name: String!
) {
  getIntegrationTestCredentials(category: $category, name: $name) {
    name
    category
    credentials
  }
}
```

**Variables (example):**

```json
{
  "category": "PSP",
  "name": "adyen"
}
```

**Supported categories:**
- `SHOP`
- `PSP`
- `SALES_CHANNEL`

**Access requirements:**
- Valid JWT token
- God mode enabled user

If no credentials are found for the combination of category + name, the API returns `404`.

## Architecture Overview

```
┌─────────────┐     GraphQL      ┌──────────────────────┐
│   Frontend   │ ───────────────► │  SuperPay Admin API   │
│   (React)    │ ◄─────────────── │  /graphql             │
└─────────────┘                  └──────────┬───────────┘
                                            │
                              ┌─────────────┼─────────────┐
                              │             │             │
                         ┌────▼────┐  ┌─────▼─────┐ ┌────▼────┐
                         │  Auth   │  │  Store    │ │ Merchant│
                         │ Module  │  │  Config   │ │ Module  │
                         └─────────┘  └─────┬─────┘ └─────────┘
                                            │
                                   ┌────────┼────────┐
                                   │        │        │
                              ┌────▼──┐ ┌───▼───┐ ┌──▼───┐
                              │Shopify│ │  PSP  │ │Sales │
                              │ Form  │ │ Form  │ │Chan. │
                              └───────┘ └───────┘ └──────┘
```

The **Dynamic Form System** is the core concept for the admin UI. Instead of the frontend hardcoding store settings forms, the backend describes what fields to render, including their types, validation rules, and conditional visibility. This allows the backend to evolve the configuration schema without frontend changes.

Read [Store Configuration](./store-configuration.md) for the full guide.