Skip to main content
GET
Authorize

Authorize

Starts the OAuth 2.0 authorization code grant flow. The merchant must be signed in to their LaunchMyStore admin when this endpoint is hit — the endpoint is protected by merchant auth and uses the merchant’s session to resolve which storeId is granting consent. On success, the endpoint returns a one-time code plus an opaque state your app must round-trip to POST /apps/oauth/token to exchange for an access token.
Apps don’t call this API directly. To request authorization from a merchant, redirect their browser to the admin consent pagehttps://app.launchmystore.io/oauth/authorize — with the same query parameters. The consent page authenticates the merchant, shows your app’s name and requested scopes, and calls this API on Approve; the browser then lands on your redirect_uri with ?code=&state= (plus client_state= echoing your own nonce, if you sent one), or ?error=access_denied on Cancel. See Authentication for the full browser flow. Before rendering, the consent page validates your client_id + redirect_uri via the public GET /apps/oauth/client-info?client_id=&redirect_uri= endpoint, which returns only your app’s public listing fields (name, developer, icon, registered scopes).
The state parameter returned by this endpoint is server-generated and bound to the authorization code server-side with a 10-minute TTL. You must echo it back on the token exchange call. Your own anti-CSRF token, if any, should be passed in the request as a separate value and is not read by the server.

Request

Query Parameters

string
required
The app’s public client identifier. Issued when the developer registers the app via POST /apps/developer/create.
string
required
The callback URL where the merchant will be redirected after consent. Must exactly match one of the URLs in app.redirectUrls. Mismatched URIs return 400 Invalid redirect URI.
string
required
Comma-separated list of scopes being requested (e.g. read_products,write_orders). Each scope must be a member of the app’s registered scope set; otherwise the endpoint returns 400 Invalid scopes: <list>. See Scopes for the 37 available scopes.
string
default:"code"
Must be code. Any other value returns 400 Unsupported response_type. Defaults to code when omitted for back-compat.
string
Optional client-side anti-CSRF nonce. The server stores this in clientState against the issued code but does not echo it back in the response — the response’s data.state is always the server-generated token. Not used for server-side validation.
string
PKCE (RFC 7636) code challenge. When supplied, the matching code_verifier must be sent on the token exchange. Length must be 43-128 characters.
string
default:"plain"
Either S256 (strongly recommended) or plain. Any other value returns 400. Only meaningful when code_challenge is also sent.

Response

integer
HTTP status code (200 on success).
string
Final response state: "success" or "error".
object

Example Response

Your app should now redirect the merchant back to your redirect_uri with code and state appended as query parameters, then immediately call POST /apps/oauth/token server-side.

Error Codes

Security Notes

  • Authorization codes expire after 10 minutes and are single-use. Replays of an already-consumed code fail with Invalid or expired authorization code on the token endpoint.
  • The server-generated state is bound to the code server-side. Both are deleted atomically when the token is issued.
  • This endpoint is not rate-limited at the gateway — it is already gated by merchant authentication.
  • For embedded apps, prefer PKCE + session tokens. See Session Tokens.