@krunal202/apple-search-ads-cli 0.1.0 → 0.1.1

package/CREDENTIALS.md

@@ -0,0 +1,63 @@
+# Getting Apple Search Ads API Credentials
+
+This takes about 5 minutes in the Apple Search Ads web UI. At the end you will have the four values `asa login` needs:
+
+```
+asa login --client-id <SEARCHADS.xxxx> --team-id <id> --key-id <id> --key-file ./asa-private-key.p8
+```
+
+## 1. Invite an API user
+
+API credentials are only available to users with an **API role** — a plain Account Admin does not see the create option.
+
+1. Sign in to [searchads.apple.com](https://searchads.apple.com)
+2. Go to **Account Settings → User Management**
+3. **Invite a user** — this can be your own email address
+4. Assign the role **API Account Manager** (read + write) or **API Account Read Only** (reporting only)
+5. Accept the invitation email and sign back in
+
+If your account belongs to multiple organizations, switch to the correct org using the selector in the top bar before continuing.
+
+## 2. Generate a key pair (private key never leaves your machine)
+
+```bash
+openssl ecparam -genkey -name prime256v1 -noout -out asa-private-key.p8
+openssl ec -in asa-private-key.p8 -pubout -out asa-public-key.pem
+chmod 600 asa-private-key.p8
+```
+
+Or just ask your LLM agent: *"generate an ES256 (prime256v1) key pair for Apple Search Ads"* — it runs the same two commands. The private key (`asa-private-key.p8`) stays on your machine; only the **public** key (`asa-public-key.pem`) is uploaded to Apple. Never commit the `.p8` file to git.
+
+## 3. Create the API credentials and upload the public key
+
+1. Go to **Account Settings → API**
+2. Click **Create API Certificate / credentials**
+3. Upload `asa-public-key.pem`
+4. Apple shows three values — copy them:
+
+| Value | Looks like |
+|---|---|
+| Client ID | `SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+| Team ID | same format (often identical to the client ID) |
+| Key ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
+
+> The **Manage API Access** list on that page (Adapty, Branch, etc.) shows third-party providers you granted access to — those are not your credentials.
+
+## 4. Log in
+
+```bash
+asa login \
+  --client-id SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
+  --team-id SEARCHADS.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
+  --key-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
+  --key-file ./asa-private-key.p8
+```
+
+`asa` verifies the credentials immediately, lists your orgs, and caches the OAuth token. Run `asa whoami` any time to confirm.
+
+## Troubleshooting
+
+- **`invalid_client` on login** — you are using App Store Connect credentials (Issuer ID + `AuthKey_XXXX.p8`). Those belong to a different system. Create credentials in the **Apple Search Ads** UI as above.
+- **No create option on the API tab** — your user lacks an API role. Go back to step 1.
+- **Lost the private key** — generate a new pair (step 2) and replace the public key on the API tab, or revoke and recreate the credentials. Apple never sees or stores your private key.
+- **HTTP 403 after login** — wrong org selected: `asa orgs list` then `asa orgs use <orgId>`.

package/LLM_GUIDE.md

@@ -46,6 +46,8 @@ Every mutating API call (create/update/delete/paste) is logged automatically wit
 
 Create credentials in **Apple Search Ads UI → Account Settings → API**. This requires a user with an **API role** (API Account Manager for read/write) — plain Account Admin does not see the create option. Invite yourself via the User Management tab if needed. Apple issues a client ID (`SEARCHADS.…`), team ID, key ID, and you upload your own ES256 (prime256v1) public key; keep the matching `.p8` private key.
 
+Full step-by-step walkthrough: [CREDENTIALS.md](CREDENTIALS.md).
+
 Note: App Store Connect keys (Issuer ID + `AuthKey_XXXX.p8`) are a different system and return `invalid_client` for this API.
 
 ## Global options

package/README.md

@@ -20,8 +20,9 @@ Requires Node.js ≥ 18. Single runtime dependency: `commander`.
 ## Quickstart
 
 ```bash
-# 1. Get API credentials: Apple Search Ads → Account Settings → API (client ID, team ID, key ID, .p8 key)
-asa login --client-id <id> --team-id <id> --key-id <id> --key-file ./AuthKey.p8
+# 1. Get API credentials — full walkthrough: CREDENTIALS.md
+#    (Apple Search Ads UI → invite an API-role user → upload a public key)
+asa login --client-id <id> --team-id <id> --key-id <id> --key-file ./asa-private-key.p8
 
 asa orgs list && asa orgs use <orgId>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krunal202/apple-search-ads-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "LLM-friendly CLI for the Apple Search Ads API",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
   "files": [
     "bin",
     "src",
-    "LLM_GUIDE.md"
+    "LLM_GUIDE.md",
+    "CREDENTIALS.md"
   ],
   "scripts": {
     "test": "node --test"