Build a secure Elonky integration

This guide explains how a shop owner creates integration credentials in the Elonky Shop Dashboard and how a server-side integration exchanges those credentials for a scoped access token.

Quick Start

Complete these four steps from the shop owner’s account and your integration backend.

1. 1
   Open Shop Settings

   Sign in to the Elonky Shop Dashboard, open Shop Settings, then select the Developer tab.

2. 2
   Create credentials

   Enter an integration name, select at least one required scope, and create the integration.

3. 3
   Store the secret safely

   Copy the client ID and one-time client secret into your server-side secret store.

4. 4
   Request an access token

   Send the credentials from your backend to POST /oauth2/token and use the returned Bearer token only for its approved scopes.

Create integration credentials

Credential management is available to authenticated shop owners in Shop Dashboard → Shop Settings → Developer. The Shop Dashboard calls Developer Service with the owner’s authenticated session and associates every integration with that owner’s shop.

Choose a name and scopes

A shop can have at most five non-deleted integrations. Names must be unique within the shop, and at least one active scope is required.

Exchange credentials for an access token

Call the public gateway token alias from your integration backend. The current contract accepts JSON credentials; it does not require a grant_type field or HTTP Basic authentication.

POST /oauth2/token
Content-Type: application/json

{
  "clientId": "<clientId>",
  "clientSecret": "<clientSecret>"
}

{
  "message": "Access token generated successfully.",
  "data": {
    "accessToken": "<accessToken>",
    "tokenType": "Bearer",
    "expiresIn": 3599
  }
}

The token type is Bearer and the access token expires after 60 minutes. expiresIn is returned in seconds and can be slightly below 3600 by the time the response is serialized.

Prepare your first authenticated request

Send the access token in the Authorization header. Never expose the client secret or access token in browser code. The gateway validates the token and derives store, client, token-version, and scope context from its claims.

Authorization: Bearer <accessToken>

Credential lifecycle and security

Treat integration credentials as production secrets and limit every integration to the minimum scopes it needs.

• Create no more than five active integration records per shop and use a distinct integration for each external system.
• Store client secrets only in a backend secret manager; never commit them to source control or include them in screenshots, logs, analytics, or frontend bundles.
• Rotating a secret prevents the old secret from issuing new tokens and increments the integration token version.
• Tokens already issued before rotation or deactivation may remain valid until their 60-minute expiry under the current gateway validation behavior.
• Disable or delete an integration when it is no longer used. A disabled or deleted integration cannot issue new tokens.
• Redact the client ID, client secret, and full access token before sharing diagnostic requests.

Errors and troubleshooting

Start with the HTTP status and confirm the request is reaching the Integration Gateway rather than another public gateway.

API Reference

Reference cards are visible for planned integration domains. Each remains clearly marked as coming soon until its public gateway route and OpenAPI specification are verified.

Get Help

When requesting support, include the timestamp, HTTP status, request path, and a trace or correlation ID if one was returned. Never include credentials or the full Bearer token.

For security, replace sensitive values with <redacted> before sharing curl, Postman, or log output.