From 91bde9dacd2036940ad4ae66196061fa56a76d6d Mon Sep 17 00:00:00 2001
From: Fwaad Ahmad <fwaad.ahmad@shopify.com>
Date: Tue, 18 Feb 2025 11:29:04 -0500
Subject: [PATCH] docs: client credentials grant in shopify-api-js

---
 docs/usage/oauth.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/docs/usage/oauth.md b/docs/usage/oauth.md
index 12527090d..8cc6a97a8 100644
--- a/docs/usage/oauth.md
+++ b/docs/usage/oauth.md
@@ -12,6 +12,7 @@ For more information on authenticating a Shopify app please see the [Types of Au
 - [Performing OAuth](#performing-oauth-1)
   - [Token Exchange](#token-exchange)
   - [Authorization Code Grant Flow](#authorization-code-grant-flow)
+  - [Client Credentials Grant](#client-credentials-grant)
 - [Using OAuth Session to make authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls)
 
 ## Session Persistence
@@ -35,6 +36,10 @@ with [token exchange](#token-exchange) instead of the authorization code grant f
     - OAuth flow that requires the app to redirect the user to Shopify for installation/authorization of the app to access the shop's data.
     - Suitable for non-embedded apps
     - Installations, and access scope changes are managed by the app
+3. [Client Credentials Grant](#client-credentials-grant)
+    - Suitable for backend apps without UI
+    - Doesn't require user interaction in the browser
+    - Access scopes can be configured either in the Developer Dashboard when creating an app version or in your app's [TOML configuration file](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration#access_scopes)
 
 ## Note about Rails
 If using in the Rails framework, we highly recommend you use the [shopify_app](https://github.com/Shopify/shopify_app) gem to perform OAuth, you won't have to follow the instructions below to start your own OAuth flow.
@@ -49,6 +54,8 @@ If you aren't using Rails, you can look at how the `ShopifyApp` gem handles OAut
       - Triggering and redirecting user to **begin** OAuth flow
     - [Callback Controller](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/callback_controller.rb)
       - Creating / storing sessions to **complete** the OAuth flow
+  - [Client Credentials](https://github.com/Shopify/shopify_app/blob/main/lib/shopify_app/auth/client_credentials.rb)
+    - Completes client credentials flow to get offline access tokens with expiration time.
 
 ## Performing OAuth
 ### Token Exchange
@@ -265,9 +272,41 @@ def callback
   end
 end
 ```
-
 ⚠️ You can see a concrete example in the `ShopifyApp` gem's [CallbackController](https://github.com/Shopify/shopify_app/blob/main/app/controllers/shopify_app/callback_controller.rb).
 
+### Client Credentials Grant
+
+> [!NOTE]
+> You should consider using the client credentials grant only when building apps for your own organization.
+
+> [!WARNING]
+> [token exchange](#token-exchange) (for embedded apps) or the [authorization code grant flow](#authorization-code-grant-flow) should be used instead of the client credentials grant, if your app is a browser based web app.
+
+#### Perform Client Credentials Grant
+Use [`ShopifyAPI::Auth::ClientCredentials`](https://github.com/Shopify/shopify-api-ruby/blob/main/lib/shopify_api/auth/client_credentials.rb) to
+exchange the [app's client ID and client secret](https://shopify.dev/docs/apps/build/authentication-authorization/client-secrets) for an access token.
+#### Input
+| Parameter      | Type                   | Required? | Default Value | Notes                                                                                                       |
+| -------------- | ---------------------- | :-------: | :-----------: | ----------------------------------------------------------------------------------------------------------- |
+| `shop`         | `String` | Yes | - | A Shopify domain name in the form `{exampleshop}.myshopify.com`. |
+
+#### Output
+This method returns the new `ShopifyAPI::Auth::Session` object from the client credentials grant, your app should store this `Session` object to be used later [when making authenticated API calls](#using-oauth-session-to-make-authenticated-api-calls).
+
+#### Example
+```ruby
+
+# `shop` is the shop domain name - "this-is-my-example-shop.myshopify.com"
+
+def authenticate(shop)
+  session = ShopifyAPI::Auth::ClientCredentials.client_credentials(
+     shop: shop,
+   )
+  SessionRepository.store_session(session)
+end
+
+```
+
 ## Using OAuth Session to make authenticated API calls
 Once your OAuth flow is complete, and you have persisted your `Session` object, you may use that `Session` object to make authenticated API calls.