> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Overview

> Overview of ERP integration options with the JTL Platform, including authentication and available endpoints

The JTL ERP API lets you read and modify JTL-Wawi data: orders, products, customers, stock, and more.

Every merchant runs the same Wawi API on their own Wawi instance. What differs is how your integration reaches it.

| Option        | Base URL                                   | Where your integration runs                               |
| ------------- | ------------------------------------------ | --------------------------------------------------------- |
| **OnPremise** | `http://127.0.0.1:64110/api/eazybusiness/` | On the merchant's machine or their local network          |
| **Cloud**     | `https://api.jtl-cloud.com/erp/`           | Anywhere. The request is forwarded to the merchant's Wawi |

The Cloud option is available when a merchant has connected their [Wawi to JTL Cloud](/get-started/create-developer-account#step-2-connect-to-jtl-wawi). The public endpoint forwards requests to their Wawi, letting your integration run off the merchant's premises without access to their network.

Both variants expose the same API surface through REST and GraphQL. They differ in:

* where your integration can be deployed
* how authentication works
* a small set of variant-specific [capabilities](/guides/cloud-apps/app-shell-ui-integration#capabilities)

## Authentication

The authentication flow depends on the variant. Cloud uses OAuth 2.0 client credentials; OnPremise uses a two-step registration flow.

<Tabs>
  <Tab title="Cloud">
    <Steps>
      <Step title="Register in the Partner Portal">
        Register your app in the [JTL Partner Portal](https://partner.jtl-cloud.com) to receive a `clientId` and `clientSecret`.
      </Step>

      <Step title="Request an access token">
        Send a POST request to `https://auth.jtl-cloud.com/oauth2/token` with Basic auth (base64 `clientId:clientSecret`) and body `grant_type=client_credentials`. The response returns a JWT access token valid for 24 hours.
      </Step>

      <Step title="Call the API">
        Include the JWT as `Authorization: Bearer <JWT>` on every request, along with the merchant's `X-Tenant-ID`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="OnPremise">
    <Steps>
      <Step title="Start registration in Wawi">
        Open JTL-Wawi (new interface) and go to **Admin > App registration**, and follow the steps to register your app. This authorizes your first API call; without it, registration requests are rejected.
      </Step>

      <Step title="Send the initial registration request">
        Send a POST request to `/authentication` with your app metadata (`AppId`, `DisplayName`, `Description`, `Version`, `ProviderName`, `ProviderWebsite`, `MandatoryApiScopes`, `OptionalApiScopes`) and an `x-challengecode` header. The API returns a `RegistrationRequestId`.
      </Step>

      <Step title="Approve in Wawi">
        The merchant approves the registration request in the Wawi admin panel.
      </Step>

      <Step title="Retrieve the API key">
        GET `/authentication/{registrationId}` with the same `x-challengecode` header. The response contains your `ApiKey` and `GrantedScopes`.
      </Step>
    </Steps>

    <Warning>
      The API key is displayed only once and cannot be retrieved again. Store it securely immediately on receipt.
    </Warning>
  </Tab>
</Tabs>

See the [OAuth 2.0 flow](/guides/essentials/authentication/oauth2-flow) for more details.

## Required HTTP Headers

Every API request must include the headers below:

<Tabs>
  <Tab title="Cloud">
    | Header          | Description                                               |
    | --------------- | --------------------------------------------------------- |
    | `Authorization` | `Bearer <JWT>` obtained from the OAuth 2.0 token endpoint |
    | `X-Tenant-ID`   | The merchant's tenant ID                                  |
  </Tab>

  <Tab title="OnPremise">
    | Header            | Description                                                 |
    | ----------------- | ----------------------------------------------------------- |
    | `Authorization`   | `Wawi <API-Key>`                                            |
    | `x-appid`         | Your application identifier, e.g. `MyApp/1.0.0`             |
    | `x-appversion`    | Your application version, e.g. `1.0.0`                      |
    | `api-version`     | Target API version, e.g. `2.0`                              |
    | `x-challengecode` | Custom value used during registration, max 30 characters.   |
    | `x-runas`         | Wawi user ID to perform the call on their behalf. Optional. |
  </Tab>
</Tabs>

See the [versioning](/guides/essentials/common-patterns/versioning) guide for more details on API versioning.

## Next Steps

<CardGroup cols={2}>
  <Card title="Available APIs" icon="list" href="/guides/erp-integration/available-apis">
    A guided tour of the REST API domains and what each one does.
  </Card>

  <Card title="Authentication" icon="key" href="/guides/essentials/authentication/oauth2-flow">
    Auth flows across Cloud Apps, OnPremise, and SCX.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Browse all REST API endpoints with request/response schemas.
  </Card>
</CardGroup>