Skill: byungkyu/salesforce-api (version 1.0.7)

--- name: salesforce description: | Salesforce CRM API integration with managed OAuth. Install only if you need Salesforce CRM administration. Connect with the narrowest Salesforce permissions available, prefer sandbox orgs for destructive or batch work, verify the intended connection ID before each request, and revoke unused connections promptly. This integration can mutate CRM records — approve only specific write actions after checking the exact sObject, record IDs, and consequence. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: 🧠 requires: env: - MATON_API_KEY --- # Salesforce Access the Salesforce REST API with managed OAuth authentication. Query records using SOQL, manage sObjects, and perform CRUD operations on your Salesforce data. ## Quick Start **CLI:** ```bash maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10' ``` ```bash maton api '/salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10' ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/salesforce/services/data/v63.0/query?q=SELECT+Id,Name,Email+FROM+Contact+LIMIT+10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://api.maton.ai/salesforce/{endpoint-path} ``` The gateway proxies requests to `{instance}.salesforce.com` (automatically replaced with your connection config) and injects your access token. Only the endpoints documented in the API Reference section below are supported — always use specific endpoint paths from that section rather than constructing arbitrary paths. ## Installation **NPM:** ```bash npm install -g @maton-ai/cli ``` **Homebrew:** ```bash brew install maton-ai/cli/maton ``` ## Authentication **CLI:** ```bash maton login # Opens browser for API key maton login --interactive # Skip browser, paste API key directly maton whoami # Show current auth state ``` **Manual:** 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key 4. Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ## Connection Management Manage your Salesforce OAuth connections at `https://api.maton.ai`. ### List Connections **CLI:** ```bash maton connection list salesforce --status ACTIVE ``` ```bash maton api -X GET /connections -f app=salesforce -f status=ACTIVE ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections?app=salesforce&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection **CLI:** ```bash maton connection create salesforce ``` ```bash maton api /connections -f app=salesforce ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'salesforce'}).encode() req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection **CLI:** ```bash maton connection view {connection_id} ``` ```bash maton api /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "{connection_id}", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "salesforce", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection **CLI:** ```bash maton connection delete {connection_id} ``` ```bash maton api -X DELETE /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Salesforce connections, specify which one to use: **CLI:** ```bash maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10' --connection {connection_id} ``` ```bash maton api /salesforce/services/data/v63.0/sobjects --connection {connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/salesforce/services/data/v63.0/sobjects') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always specify the connection to ensure requests go to the intended account. ## Security & Permissions - **IMPORTANT:** Treat `MATON_API_KEY` as a secret — do not log it, include it in chats or prompts visible to others, or expose it in shared files or outputs. The key authenticates with Maton, and the Salesforce connection is independently scoped via OAuth. Use the narrowest Salesforce permissions available, rotate the key if exposed at [maton.ai/settings](https://maton.ai/settings), and revoke unused connections promptly. - Access is scoped to the Salesforce resources permitted by the connected account's OAuth scopes. Only install if you need Salesforce CRM administration. Prefer sandbox orgs for destructive or batch testing. - **Default to read-only operations.** Always start with SOQL queries or GET requests to confirm record IDs and field values before proposing any changes. - **All write operations require explicit user approval with specific details.** Before executing any POST, PATCH, DELETE, or composite/batch call: 1. Retrieve and display the target resource (sObject type, record ID, record name) so the user can verify. 2. Clearly describe the intended effect (e.g., "This will delete Opportunity 'Acme Deal' (ID: 006xx) — this cannot be undone"). 3. Wait for explicit user confirmation before proceeding. - **Batch and composite operations require extra caution.** These can modify multiple records in a single call. List every affected record and confirm before execution. ## API Reference ### SOQL Query ```bash GET /salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+10 ``` Example: ```bash maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10' ``` Complex query: ```bash GET /salesforce/services/data/v63.0/query?q=SELECT+Id,Name,Email+FROM+Contact+WHERE+Email+LIKE+'%25example.com'+ORDER+BY+CreatedDate+DESC ``` Example: ```bash maton salesforce query "SELECT Id,Name,Email FROM Contact WHERE Email LIKE '%example.com' ORDER BY CreatedDate DESC" ``` ### Get Object ```bash GET /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ ``` Example: ```bash maton salesforce record view 0035g00000XYZ --type Contact ``` ### Create Object ```bash POST /salesforce/services/data/v63.0/sobjects/Contact Content-Type: application/json { "FirstName": "John", "LastName": "Doe", "Email": "[REDACTED_SECRET]" } ``` Example: ```bash maton salesforce record create --type Contact --data '{"FirstName":"John","LastName":"Doe","Email":"[REDACTED_SECRET]"}' ``` ### Update Object ```bash PATCH /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ Content-Type: application/json { "Phone": "+1234567890" } ``` Example: ```bash maton salesforce record update 0035g00000XYZ --type Contact --data '{"Phone":"+1234567890"}' ``` ### Delete Object ```bash DELETE /salesforce/services/data/v63.0/sobjects/Contact/0035g00000XYZ ``` Example: ```bash maton salesforce record delete 0035g00000XYZ --type Contact ``` ### Describe Object (get schema) ```bash GET /salesforce/services/data/v63.0/sobjects/Contact/describe ``` Example: ```bash maton salesforce object describe Contact ``` ### List Objects ```bash GET /salesforce/services/data/v63.0/sobjects ``` Example: ```bash maton salesforce object list ``` ### Search (SOSL) ```bash GET /salesforce/services/data/v63.0/search?q=FIND+{John}+IN+ALL+FIELDS+RETURNING+Contact(Id,Name) ``` Example: ```bash maton salesforce search 'FIND {John} IN ALL FIELDS RETURNING Contact(Id,Name)' ``` ### Get API Limits ```bash GET /salesforce/services/data/v63.0/limits ``` Example: ```bash maton salesforce limit view ``` ### Get Current User Example: ```bash maton salesforce whoami ``` ### Composite Request (batch multiple operations) ```bash POST /salesforce/services/data/v63.0/composite Content-Type: application/json { "compositeRequest": [ { "method": "GET", "url": "/services/data/v63.0/sobjects/Contact/003XXXXXXX", "referenceId": "contact1" }, { "method": "GET", "url": "/services/data/v63.0/sobjects/Account/001XXXXXXX", "referenceId": "account1" } ] } ``` Example: ```bash echo '{"compositeRequest":[{"method":"GET","url":"/services/data/v63.0/sobjects/Contact/003XXXXXXX","referenceId":"contact1"},{"method":"GET","url":"/services/data/v63.0/sobjects/Account/001XXXXXXX","referenceId":"account1"}]}' \ | maton salesforce composite call -F - ``` ### Composite Batch Request ```bash POST /salesforce/services/data/v63.0/composite/batch Content-Type: application/json { "batchRequests": [ {"method": "GET", "url": "v63.0/sobjects/Contact/003XXXXXXX"}, {"method": "GET", "url": "v63.0/sobjects/Account/001XXXXXXX"} ] } ``` Example: ```bash echo '{"batchRequests":[{"method":"GET","url":"v63.0/sobjects/Contact/003XXXXXXX"},{"method":"GET","url":"v63.0/sobjects/Account/001XXXXXXX"}]}' \ | maton salesforce composite batch -F - ``` ### sObject Collections Create (batch create) ```bash POST /salesforce/services/data/v63.0/composite/sobjects Content-Type: application/json { "allOrNone": true, "records": [ {"attributes": {"type": "Contact"}, "FirstName": "John", "LastName": "Doe"}, {"attributes": {"type": "Contact"}, "FirstName": "Jane", "LastName": "Smith"} ] } ``` Example: ```bash maton salesforce record create --all-or-none --data '[{"attributes":{"type":"Contact"},"FirstName":"John","LastName":"Doe"},{"attributes":{"type":"Contact"},"FirstName":"Jane","LastName":"Smith"}]' ``` ### sObject Collections Delete (batch delete) ```bash DELETE /salesforce/services/data/v63.0/composite/sobjects?ids=003XXXXX,003YYYYY&allOrNone=true ``` Example: ```bash maton salesforce record delete 003XXXXX 003YYYYY --all-or-none ``` ### Get Updated Records ```bash GET /salesforce/services/data/v63.0/sobjects/Contact/updated/?start=2026-04-30T00:00:00Z&end=2026-05-05T00:00:00Z ``` Example: ```bash maton salesforce record list --type Contact --start 2026-04-30T00:00:00Z --end 2026-05-05T00:00:00Z ``` ### Get Deleted Records ```bash GET /salesforce/services/data/v63.0/sobjects/Contact/deleted/?start=2026-04-30T00:00:00Z&end=2026-05-05T00:00:00Z ``` Example: ```bash maton salesforce record list --type Contact --start 2026-04-30T00:00:00Z --end 2026-05-05T00:00:00Z --changes deleted ``` ### List API Versions ```bash GET /salesforce/services/data/ ``` Example: ```bash maton salesforce version list ``` ## Common Objects - `Account` - Companies/Organizations - `Contact` - People associated with accounts - `Lead` - Potential customers - `Opportunity` - Sales deals - `Case` - Support cases - `Task` - To-do items - `Event` - Calendar events ## Pagination Salesforce uses cursor-based pagination. The CLI automatically paginates with '--paginate'. Example: ```bash maton salesforce query 'SELECT Id,Name FROM Contact' --paginate ``` ## Code Examples ### CLI ```bash # Query contacts maton salesforce query 'SELECT Id,Name FROM Contact LIMIT 10' # View a specific record maton salesforce record view 0035g00000XYZ --type Contact # Create a new contact maton salesforce record create --type Contact --data '{"FirstName":"John","LastName":"Doe"}' # Describe an object schema maton salesforce object describe Contact # Check authenticated user maton salesforce whoami # Check API limits maton salesforce limit view ``` ### JavaScript ```javascript const response = await fetch( 'https://api.maton.ai/salesforce/services/data/v63.0/query?q=SELECT+Id,Name+FROM+Contact+LIMIT+5', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ``` ### Python ```python import os import requests response = requests.get( 'https://api.maton.ai/salesforce/services/data/v63.0/query', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'q': 'SELECT Id,Name FROM Contact LIMIT 5'} ) ``` ## Notes - Use URL encoding for SOQL queries (spaces become `+`) - Record IDs are 15 or 18 character alphanumeric strings - API version (v63.0) can be adjusted; latest is v65.0 - Update and Delete operations return HTTP 204 (no content) on success - Dates for updated/deleted queries use ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ` - Use `allOrNone: true` in batch operations for atomic transactions - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping. ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing Salesforce connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Salesforce API | ### Troubleshooting: API Key Issues **CLI:** 1. Check your auth state: ```bash maton whoami ``` 2. Verify the API key is valid by listing connections: ```bash maton connection list ``` **Manual:** 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `salesforce`. For example: - Correct: `https://api.maton.ai/salesforce/services/data/v63.0/query` - Incorrect: `https://api.maton.ai/services/data/v63.0/query` ## Resources - [REST API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/intro_rest.htm) - [List sObjects](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_describeGlobal.htm) - [Describe sObject](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_describe.htm) - [Get Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_retrieve_get.htm) - [Create Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm) - [Update Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_update_fields.htm) - [Delete Record](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_delete_record.htm) - [Query Records (SOQL)](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_query.htm) - [Composite Request](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_composite_post.htm) - [sObject Collections](https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_composite_sobjects_collections_create.htm) - [SOQL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_soql.htm) - [SOSL Reference](https://developer.salesforce.com/docs/atlas.en-us.soql_sosl.meta/soql_sosl/sforce_api_calls_sosl.htm) - [Maton CLI Manual](https://cli.maton.ai/manual) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)