OAuth

OpenSylo uses the Authorization Code grant type (RFC 6749) with PKCE support (RFC 7636). This flow requires the merchant (the user on your platform) to explicitly grant consent for data sharing.

Overview

Merchant Browser          Your Server           OpenSylo
     |                        |                      |
     |  1. Click "Connect"    |                      |
     |----------------------->|                      |
     |                        |  2. Generate PKCE    |
     |                        |     + state          |
     |  3. Redirect           |                      |
     |<-----------------------|                      |
     |                        |                      |
     |  4. Login + Consent    |                      |
     |----------------------------------------------->|
     |                        |                      |
     |  5. Redirect with code |                      |
     |<-----------------------------------------------|
     |                        |                      |
     |  6. Forward code       |                      |
     |----------------------->|                      |
     |                        |  7. Exchange code    |
     |                        |--------------------->|
     |                        |  8. Tokens returned  |
     |                        |<---------------------|
     |  9. Success            |                      |
     |<-----------------------|                      |

Step 1 — Generate PKCE Values

PKCE (Proof Key for Code Exchange) is recommended for all clients and required for public clients.

Method	Description
`S256`	Recommended. SHA-256 hash of the verifier, base64url-encoded.
`plain`	Verifier sent as-is (only for development/testing).

Step 2 — Redirect to Authorization

Redirect the merchant's browser to the OpenSylo authorization endpoint:

GET /oauth/authorize

Parameter	Required	Description
`client_id`	Yes	Your marketplace client ID
`redirect_uri`	Yes	One of your registered redirect URIs
`response_type`	Yes	Must be `code`
`scope`	Yes	Space-separated list of requested scopes
`state`	Recommended	Opaque CSRF token you generate; returned unchanged in the callback
`code_challenge`	Recommended	PKCE code challenge (S256 or plain)
`code_challenge_method`	Recommended	`S256` (recommended) or `plain`

Example URL:

https://api.opensylo.com/oauth/authorize
  ?client_id=yourmarketplace_client_a1b2c3d4
  &redirect_uri=https://yourmarketplace.com/oauth/callback
  &response_type=code
  &scope=data.share.sales data.share.profile credit.score.read
  &state=random_csrf_token_123
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

OpenSylo presents a login page (if the merchant is not already authenticated) followed by a consent screen listing the requested permissions. The merchant can Allow or Deny.

On success, OpenSylo redirects to your redirect_uri:

https://yourmarketplace.com/oauth/callback
  ?code=<authorization_code>
  &state=random_csrf_token_123

On denial:

https://yourmarketplace.com/oauth/callback
  ?error=access_denied
  &error_description=User+denied+authorization
  &state=random_csrf_token_123

The authorization code expires in 5 minutes and can only be used once.

Always verify the state parameter matches what you sent to prevent CSRF attacks.

Step 4 — Exchange Code for Tokens

POST /oauth/token

Response:

{
  "access_token": "<opaque_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque_token>",
  "scope": "data.share.sales data.share.profile credit.score.read"
}

Token Lifetimes

Token	Lifetime	Purpose
`access_token`	1 hour (3600 seconds)	Used in `Authorization: Bearer` header for API calls
`refresh_token`	30 days	Used to obtain a new access token without re-prompting the merchant

Step 5 — Refresh Tokens

When the access token expires, use the refresh token to get a new one:

Response:

{
  "access_token": "<new_access_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "data.share.sales data.share.profile credit.score.read"
}

The refresh response does not include a new refresh token. Continue using the original refresh token until it expires (30 days).

Step 6 — Revoke Tokens

POST /oauth/revoke

Per the OAuth specification, this endpoint returns 200 OK even if the token is invalid or already revoked.

Discovery — Client Metadata

GET /oauth/client-metadata?client_id=<your_client_id>

Returns the OAuth capabilities supported by OpenSylo:

{
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "response_types_supported": ["code"],
  "scopes_supported": [
    "data.share.sales", "data.share.fulfillment", "data.share.payouts",
    "data.share.risk", "data.share.profile", "credit.score.read", "repayment.report",
    "sales.read", "sales.write", "repayments.read", "repayments.write",
    "account.flags.read", "account.flags.write", "merchant.profile.read"
  ],
  "code_challenge_methods_supported": ["S256", "plain"],
  "token_endpoint_auth_methods_supported": ["client_secret_post"]
}

Available Scopes

Scope	Description
`data.share.sales`	Share sales and GMV data with OpenSylo
`data.share.fulfillment`	Share order fulfillment and delivery metrics
`data.share.payouts`	Share payout and cash flow information
`data.share.risk`	Share account status and risk information
`data.share.profile`	Share merchant business profile information
`credit.score.read`	Access credit scores calculated by OpenSylo
`repayment.report`	Report loan repayments collected from merchant sales

Legacy scopes (for backward compatibility):

Scope	Description
`sales.read`	Share sales and transaction data
`sales.write`	Share sales records with OpenSylo
`repayments.read`	Access repayment information
`repayments.write`	Report repayments on behalf of merchant
`account.flags.read`	Share account status and flags
`account.flags.write`	Update account flags
`merchant.profile.read`	Share merchant profile information
`marketplace.write`	Share merchant data for credit scoring
`marketplace.read`	Access credit scores from OpenSylo

Overview#

Step 1 — Generate PKCE Values#

Step 2 — Redirect to Authorization#

Step 3 — Merchant Grants Consent#

Step 4 — Exchange Code for Tokens#

Token Lifetimes#

Step 5 — Refresh Tokens#

Step 6 — Revoke Tokens#

Discovery — Client Metadata#

Available Scopes#