Authentication

IoneShop supports complementary auth modes. Pick the narrowest that fits the client.

Mode	Status	Best for	Lifetime
API keys	Available	Server-to-server, ERP, n8n, cron	Long-lived; rotatable
OAuth 2.0	In development	Third-party apps, partners, marketplaces	Access token short; refresh optional
JWT (user session)	Platform IdP	Merchant BO / custom frontends acting as staff	Session-bound

OAuth 2.0 for partner applications is currently in development. Use scoped API keys (isk_…) for all production integrations today. Endpoint shapes below are the target contract and may still change before GA.

API keys

Format

isk_live_********************************
isk_test_********************************

isk = IoneShop Key
live / test = environment
Secret material is shown once at creation

Usage

Authorization: Bearer isk_live_...

Alternatively (automation tools that prefer a dedicated header):

X-IoneShop-Api-Key: isk_live_...

Do not put keys in query strings, mobile apps, or public storefronts.

Lifecycle

Create in BO → Developers (Owner / Admin / Integration Manager)
Assign scopes (see Authorization)
Store in a secrets manager (Vault, KMS, cloud secret store)
Rotate: create new key → deploy → revoke old key
Expire: optional expires_at; platform may force expiry on plan change / suspend

Compromised key: revoke immediately, rotate, review audit log for api_key.* events.

OAuth 2.0 (Authorization Code + PKCE) — in development

Status: in development — not available for partner apps yet. For apps that will act on behalf of a merchant who installs your integration, plan against the contract below; ship with API keys until OAuth GA is announced in the changelog.

Endpoints (contract — not live)

These URLs are the planned partner OAuth surface. They are not callable yet (auth.ioneshop.eu currently hosts the staff IdP only). Do not hard-code production traffic against them until the changelog marks OAuth Available.

Authorization: https://auth.ioneshop.eu/oauth/authorize   # planned
Token:         https://auth.ioneshop.eu/oauth/token       # planned
Revoke:        https://auth.ioneshop.eu/oauth/revoke      # planned

Flow (summary)

Register an app → receive client_id (+ client_secret for confidential clients)
Redirect merchant to authorize with scope, redirect_uri, state, PKCE code_challenge
Exchange code + code_verifier for tokens
Call API with Authorization: Bearer <access_token>

Token response (example)

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_...",
  "scope": "products.read orders.read orders.write",
  "tenant_id": "ten_01J..."
}

Public clients (SPA) must use PKCE and must not ship a client secret. Prefer backend-for-frontend.

JWT (staff / storefront sessions)

Short-lived JWTs issued by the platform IdP (auth.ioneshop.eu) for interactive users. Partners building custom admin UIs should use documented BO/session patterns — not embed long-lived API keys in browsers. Partner OAuth for third-party apps is in development.

Claims of interest (illustrative):

{
  "sub": "usr_...",
  "tenant_id": "ten_...",
  "role": "admin",
  "scopes": ["products.write"],
  "exp": 1735689600
}

Machine identity checklist

[ ] Key/token stored outside git
[ ] Separate sandbox vs production credentials
[ ] Scopes least privilege
[ ] Rotation calendar (≤ 90 days recommended; Enterprise may mandate shorter)
[ ] Alerting on 401 spike after deploy