Authentication
Learn about Cartly's authentication methods: Public API, Session, JWT, and OAuth 2.0.
Authentication Methods
| Method | Use Case | Auth Header |
|---|---|---|
| Public (none) | Storefront API — products, collections, search | X-Shop-ID: {shop_id} |
| Session Cookie | Customer accounts — orders, addresses, wishlist | __session cookie |
| JWT Bearer | Admin panel — product management, order processing | Authorization: Bearer {token} |
| OAuth 2.0 | Third-party apps — marketplace integrations | Authorization: Bearer {access_token} |
OAuth 2.0 Flow
Cartly implements the standard Authorization Code flow per RFC 6749:
- Register your app — Create an OAuth app in the Cartly admin with redirect URIs and requested scopes
- Authorization request — Redirect merchant to
/oauth/authorize - User consent — Merchant approves requested permissions
- Token exchange — Exchange authorization code for access + refresh tokens
- API access — Use access token in Bearer header
OAuth Scopes
Available permission scopes for OAuth applications
| Name | Type | Required | Description |
|---|---|---|---|
| products:read | scope | No | View products and variants |
| products:write | scope | No | Create, update, and delete products |
| orders:read | scope | No | View orders and order history |
| orders:write | scope | No | Update order status and fulfillment |
| customers:read | scope | No | View customer information |
| customers:write | scope | No | Create and update customers |
| metafields:read | scope | No | View custom metafields |
| metafields:write | scope | No | Create, update, and delete metafields |
| webhooks:manage | scope | No | Manage webhook subscriptions |
| shop:read | scope | No | View shop settings and configuration |
| collections:read | scope | No | View product collections |
| shipping:read | scope | No | View shipping zones and rates |
| analytics:read | scope | No | View analytics and reports |
Code Examples
bash
# Step 1: Redirect user to authorize
curl "https://cartly.pro/oauth/authorize?\
client_id=YOUR_CLIENT_ID&\
redirect_uri=https://yourapp.com/callback&\
scope=products:read+orders:read&\
response_type=code"
# Step 2: Exchange code for token
curl -X POST https://cartly.pro/oauth/token \
-H "Content-Type: application/json" \
-d '{"grant_type":"authorization_code","code":"AUTH_CODE","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_SECRET","redirect_uri":"https://yourapp.com/callback"}'