OAuth for Platforms

Marketplaces, shop systems and other platforms can connect the Cockpit accounts of their sellers via OAuth2 (authorization-code flow). Every seller keeps their own Cockpit account and billing. The seller logs into Cockpit, approves the requested permissions, and your platform receives an access token that acts on behalf of exactly this account.

If you only connect your own account, you do not need OAuth. Use an API key from the dashboard instead.

1. Register Your Client

Client ID and client secret are issued by Shirtigo. Contact our support and provide:

• the name of your platform, which is shown to sellers on the consent screen
• your redirect URI, e.g. https://example.com/shirtigo/callback

Each client has exactly one redirect URI, and it has to match exactly, including scheme, path and trailing slash. Keep the client secret on your server, never in a browser or app.

2. Send the Seller to Cockpit

Redirect the seller's browser to:

GET https://cockpit.shirtigo.com/oauth/authorize
    ?response_type=code
    &client_id=YOUR_CLIENT_ID
    &redirect_uri=https://example.com/shirtigo/callback
    &scope=read-user read-design write-design read-project write-project read-order write-order read-webhook write-webhook
    &state=RANDOM_VALUE

Encode the parameters as usual, scopes are separated by spaces. The seller logs in if necessary and approves the request. Cockpit then redirects to your redirect URI:

https://example.com/shirtigo/callback?code=AUTHORIZATION_CODE&state=RANDOM_VALUE

Check that state is the value you sent. If the seller denies the request, the redirect carries error=access_denied instead of code. The code is valid for 10 minutes.

3. Exchange the Code for a Token

From your server:

POST https://cockpit.shirtigo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://example.com/shirtigo/callback
&code=AUTHORIZATION_CODE

redirect_uri must be the same value as in step 2. The response contains access_token, refresh_token and expires_in. Both tokens are valid for one year. Store them per seller and send the access token with every API request:

Authorization: Bearer ACCESS_TOKEN
Accept: application/json

4. Renew the Token

Before the access token expires, request a new one:

POST https://cockpit.shirtigo.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&refresh_token=REFRESH_TOKEN

Each refresh returns a new access token and a new refresh token, and the old ones stop working. Always store the new refresh token.

Scopes

Request only the scopes your integration needs. A request to an endpoint whose scope was not granted is rejected.

Scope	Allows
read-user	Read account information
write-user	Modify account information
read-design	Read designs
write-design	Upload and modify designs
read-project	Read projects and products
write-project	Create and modify projects and products
read-order	Read orders, including shipping status and tracking
write-order	Place, update and cancel orders
read-warehouse-product	Read warehouse products
write-warehouse-product	Create and modify warehouse products
read-webhook	Read webhooks
write-webhook	Create and modify webhooks
read-stats	Read sales statistics
read-storefront	Read one-click shops, their sales and coupons
write-storefront	Create and modify one-click shops and coupons
read-commission	Read commissions, payouts and payout receipts

A typical fulfillment integration that uploads artwork, creates products, places orders and receives tracking needs read-user, read-design, write-design, read-project, write-project, read-order, write-order, read-webhook and write-webhook.

Order Updates and Tracking

Register webhooks per seller with that seller's token. Order.shipped carries tracking_code and tracking_url, so you can pass tracking on to the buyer without polling. See Status & Webhooks.

Testing

There is no sandbox. Use a separate Cockpit account with prepayment and orders with "is_onhold": true, as described in Testing Your Integration.