title: OAuth 2.0

description: Use OAuth 2.0 to authorize third-party applications on behalf of Wontopos users.

OAuth 2.0

Use OAuth 2.0 when building applications that act on behalf of Wontopos users.

Flow overview

┌──────────┐     1. Redirect      ┌───────────────┐
│  User's  │ ──────────────────▶  │   Wontopos    │
│ Browser  │                      │  Auth Server  │
│          │ ◀──────────────────  │               │
└──────────┘   2. Auth code       └───────────────┘
     │                                   │
     │ 3. Send code                      │
     ▼                                   │
┌──────────┐  4. Exchange code    ┌───────────────┐
│  Your    │ ──────────────────▶  │   Wontopos    │
│  Server  │                      │  Token API    │
│          │ ◀──────────────────  │               │
└──────────┘  5. Access token     └───────────────┘

Authorization URL

https://platform.wontopos.com/oauth/authorize

Parameter	Required	Description
`client_id`	Yes	Your application’s client ID
`redirect_uri`	Yes	URL to redirect after authorization
`response_type`	Yes	Must be `code`
`scope`	Yes	Space-separated list of scopes
`state`	Yes	Random value to prevent CSRF attacks

Example authorization URL

https://platform.wontopos.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=marketplace:read subscriptions:write
  &state=RANDOM_STATE_VALUE

Token exchange

After the user authorizes, Wontopos redirects to your redirect_uri with a code parameter.

POST /oauth/token

Parameter	Type	Required	Description
`grant_type`	`string`	Yes	Must be `authorization_code`.
`code`	`string`	Yes	The authorization code from the callback.
`redirect_uri`	`string`	Yes	Must match the original redirect URI.
`client_id`	`string`	Yes	Your application’s client ID.
`client_secret`	`string`	Yes	Your application’s client secret.

# cURL
curl https://api.wontopos.com/oauth/token 
  -X POST 
  -d grant_type=authorization_code 
  -d code=AUTH_CODE 
  -d redirect_uri=https://yourapp.com/callback 
  -d client_id=YOUR_CLIENT_ID 
  -d client_secret=YOUR_CLIENT_SECRET

// JavaScript
const res = await fetch("https://api.wontopos.com/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code: "AUTH_CODE",
    redirect_uri: "https://yourapp.com/callback",
    client_id: "YOUR_CLIENT_ID",
    client_secret: "YOUR_CLIENT_SECRET",
  }),
});

Response:

{
  "access_token": "at_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_live_...",
  "scope": "marketplace:read subscriptions:write"
}

Refresh tokens

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token.

POST /oauth/token

Parameter	Type	Required	Description
`grant_type`	`string`	Yes	Must be `refresh_token`.
`refresh_token`	`string`	Yes	The refresh token from the original exchange.
`client_id`	`string`	Yes	Your application’s client ID.
`client_secret`	`string`	Yes	Your application’s client secret.

curl https://api.wontopos.com/oauth/token 
  -X POST 
  -d grant_type=refresh_token 
  -d refresh_token=rt_live_... 
  -d client_id=YOUR_CLIENT_ID 
  -d client_secret=YOUR_CLIENT_SECRET

Refresh token rotation

Each refresh returns a new refresh token. The previous refresh token is invalidated. Store the new token immediately.

Scopes

OAuth tokens are limited to the scopes requested during authorization. See the full list of available scopes.

Scope downgrade only

Users can remove scopes during authorization but cannot add scopes beyond what was requested.