Skip to main content

Developers: OAuth Apps

Audience: Developer (ISV / third-party app builder)

Use OAuth Apps when one external app must connect to many merchants through consent/install flow.

Managed In Dashboard​

  • Settings -> Developers -> OAuth Apps

App Credentials​

  • client_id format: eshopos_ca_...
  • client_secret format: eshopos_test_cs_... or eshopos_live_cs_...
  • client_secret is shown one time on create/rotate.

Merchant Management Endpoints​

  • GET /api/v1/merchant/developer/apps
  • POST /api/v1/merchant/developer/apps
  • GET /api/v1/merchant/developer/apps/{appID}
  • PATCH /api/v1/merchant/developer/apps/{appID}
  • POST /api/v1/merchant/developer/apps/{appID}/rotate-secret
  • DELETE /api/v1/merchant/developer/apps/{appID}

OAuth Protocol Endpoints​

  • GET /api/public/v1/oauth/authorize
  • POST /api/public/v1/oauth/authorize/consent
  • POST /api/public/v1/oauth/token
  • POST /api/public/v1/oauth/revoke

Supported grants:

  • authorization_code
  • refresh_token

Scope Rules​

Allowed app scopes:

  • public:read
  • public:write
  • public:*

End-to-End Flow​

  1. Merchant creates app, sets redirect URIs and allowed scopes.
  2. App sends merchant to /oauth/authorize?....
  3. Merchant approves consent.
  4. App exchanges code at /oauth/token.
  5. App calls /api/public/v1/* with Authorization: Bearer eshopos_oat_....

Token Exchange Example​

BASE_URL="http://localhost:8080"

curl -sS -X POST "$BASE_URL/api/public/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "eshopos_ca_replace_me",
    "client_secret": "eshopos_test_cs_replace_me",
    "code": "eshopos_oac_replace_me",
    "redirect_uri": "https://app.example.com/callback",
    "code_verifier": "pkce_verifier"
  }'