Written guide
Overview
Appmint Integration Config connects provider settings to the features that use them. This course takes a configuration through creation, a controlled test and a real consuming feature. A saved key alone does not prove that checkout, shipping or messaging is connected.
1. Choose the integration
Retained catalogue capture: provider cards include EasyPost, Shippo and SMTP. Available providers are not connected configurations.
Use Integration Builder when adding a provider; use Configurations when editing an account already connected. Search by the actual provider name before applying category filters. In the retained catalogue, many providers were categorized API; a zero Messaging or Payment category therefore did not prove the corresponding provider was absent. Read the card's use cases and confirm the provider name in the opened configuration.
Why this matters
Gateway Manager separates saved Configurations, the Integration Builder catalogue and API Playground operations. Provider fields come from the provider’s schema; they are not identical across services.
Follow these steps
Open Integration Config. Choose Integration Builder and search the actual provider name. Narrow with Database, API, Webhook, Messaging, Storage, Analytics, Payment or Auth, or sort by Name. Open the provider and read its description/use cases. Create its configuration. Keep the provider identity visible. The initial status is inactive; do not silently present it as enabled.
Check the result: A new configuration uses the intended provider and its own schema.
2. Enter credentials and save
Retained SMTP setup: name/type/priority/provider are visible; credentials are incomplete and there is no successful test result.
- Rename the configuration to identify the account and environment, for example Website email — training. Confirm Provider before entering credentials.
- Read Type and Use Cases. Set only the jobs this provider should handle. Do not switch unrelated gateways off to force a test through.
- Enter the fields supplied by this provider's form. For SMTP those belong to your mailbox service; a payment provider's API key is not an SMTP login.
- Read Priority before changing it: the configuration guidance says higher priority is tried first where more than one gateway can perform the job. This is routing configuration, not the visual order of catalogue cards.
- Test the intended configuration, inspect the actual returned result, save, and reopen from Configurations. Check status separately; a newly created inactive record is not a live connection.
A successful provider test and a successfully delivered email or purchased label are different results. Finish the consuming feature's controlled operation before declaring that feature ready.
Why this matters
Each provider asks for its own connection details. Keep sandbox and production accounts separate, and use the account intended for this organization.
Follow these steps
Give the configuration a recognizable Name. Fill the required fields displayed by this provider, using the matching provider account’s credentials, endpoint and environment choices where exposed. Do not paste one provider’s fields into another. Run Test and inspect the actual success or error response. Save, return to Configurations, search the name and reopen it. Confirm the stored provider, use cases and status. A test result clears after save, so perform a fresh test when configuration changes.
Check the result: Saved settings persist and the current configuration has its own recorded test result.
3. Try a controlled operation
Retained capture: No active integrations and no API key selected. No provider operation or successful request is shown.
If you see this empty state, return to Configurations and check the intended record's saved provider and status. Do not select another provider merely to make the list nonempty. When the integration is available, select it, inspect the documented operation and its request fields, then choose the intended authentication method. Start with a supported read/test operation; sending messages, buying labels or charging payments changes external state. Inspect the response body as well as the request status, and verify any produced record in its destination.
Why this matters
API Playground calls the selected integration. Some operations send messages, create shipments or purchase numbers; the word Test does not make them simulated.
Follow these steps
Open API Playground and select the saved configuration. Expand a read operation supported by that provider, such as message history or storage listing. Fill its actual parameters, run Test once and inspect the response. For an intentionally authorized write, use a controlled recipient or sandbox resource and verify the provider-side result. If the operation exposes Request Data (JSON), supply the documented object for that operation, not an arbitrary wrapper. Keep an error response on screen and correct its specific parameter or access problem before retrying.
Check the result: A real response is associated with the selected provider/configuration; write effects are independently checked.
4. Connect the feature that consumes it
Why this matters
A working provider test and a working Appmint feature are separate proofs. Checkout, shipping and communication select or resolve configuration through their own feature settings.
Follow these steps
Open the consuming feature, such as payment configuration in the storefront course or the shipping provider setup. Select the intended saved provider configuration where that screen offers it. Save and execute one controlled end-to-end action from the customer-facing feature. Return to its order, shipment or message record and compare the reference with the provider response. If Playground works but the feature fails, inspect the feature’s chosen configuration and environment before replacing credentials.
Check the result: The actual customer or staff workflow reaches the intended provider.
5. Maintain, inspect and export examples safely
Why this matters
Configurations supports status/category filters, edit, test, JSON inspection and deletion. Generated API examples can contain your real authentication values.
Follow these steps
Filter Configurations by Active, Inactive, Testing or Error and the relevant category. Open View JSON only with secret fields concealed in any capture. Edit a controlled value, save and retest. In API Playground inspect its API Key/Auth Token options and generated request, replacing real tokens before sharing. The current live test uses integration_call while generated curl uses the operation’s upstream endpoint; verify the external example independently before claiming equivalence. Delete only a disposable configuration after checking no demonstrated feature depends on it; review every selected entry before Bulk Delete.
Check the result: Maintenance affects the intended configuration, and copied examples contain no exposed credentials.
Troubleshooting and recovery
Keep the exact record and operation visible when reading an error. Inspect persisted state before retrying a write; a timeout does not prove nothing happened. Correct the specific cause and verify the resulting record and consumer independently. An enabled feature, successful configuration save or administrative status is not proof of an external delivery, access boundary or money movement. Preserve unsupported behavior rather than simulating success.
Next steps
You can now use the module’s records and controls in context, and check the result at the point where it matters. Return to the relevant chapter for the advanced path and its verification.
Limitations and checks
Current gateway app, builder, list, store and playground inspected. Provider schemas are dynamic. No provider connection or external request executed here. Playground live call and generated curl use different routes; external parity is pending proof. OAuth-specific configuration must follow the provider schema rather than an invented universal OAuth button.
BusinessMade API keys — supporting guide
BusinessMade entry: Account → API keys (/account/api-keys).
These keys authenticate software to the organization. They are not the Device Hub connection string or an employee phone registration token. Keep a separate key per integration and verify the actual API scope enforcement described below.
Scope: This BusinessMade route uses the shared component whose complete procedures follow. Use the BusinessMade menu and organization throughout. Shared references are implementation evidence, not instructions to switch products. These written steps have not been replayed as a new BusinessMade live walkthrough.
Written course script · documented draft · Authorization and live requests pending
This course covers the actual Account API Keys page and current AppEngine authentication contract. The visible Permissions selector is not sufficient evidence of end-to-end scope enforcement. That boundary is explicitly included below.
Overview
API Keys gives a server-side integration its own credential, name, expiry and request limits. We'll create a training key, authenticate it against the intended organization, inspect its usage and replace it without confusing the saved prefix with the secret.
Prepare
Use a training organization, the intended key owner and an authorized local/server API client. Read its configured AppEngine base URL rather than guessing a public hostname. Store the organization ID and secret privately. Use a disposable collection record for later access tests.
1. Inspect existing keys and choose the right owner
Open Account → API Keys. Review Active Keys and Inactive Keys, and use Search keys... to find an existing connector before creating another. Inspect its name, displayed scopes, status, created date and Last Used.
These are the current user's keys in this organization. The name should identify the integration so you can later trace usage or replace the right credential.
An inactive-tab row can be inactive or revoked; read its actual status. A failed list request is not evidence of no keys. Reload after correcting the reported error.
2. Create the key with explicit settings
Choose Create New Key and complete:
- API Key Name:
training-record-reader, within the form's 3–100 character range. - Description: identify the training client and intended read-only task.
- Permissions: select
read:datafor the intended example, rather than every scope. - Rate Limits: inspect Requests per minute, hour and day. The current form offers defaults 100, 1,000 and 10,000 and positive limits up to 1,000 / 10,000 / 100,000 respectively. These are configuration values, not a measured service-capacity guarantee.
- Expiration Date: choose a future date appropriate to the training exercise, or deliberately leave it unset if that is the intended policy.
Choose Save API Key and wait for the result. Name and at least one valid scope are required. A date in the past is rejected by the client validation. Correct returned errors rather than assuming the form saved because fields were filled.
I'll name this for its consumer, choose the intended read permission and set an expiry. Now I'll save and transfer the returned secret privately to that client's configuration.
The current create form has no IP-whitelist field, even though the general page advice mentions IP restrictions. Do not invent one or teach legacy App Credentials' field as part of this screen.
Recognize the BusinessMade key-creation form
Historical BusinessMade creation form. No permission is selected and no secret is visible. The lower expiry control requires scrolling; the upper Save API Key control submits the completed form. This image is not evidence of a saved key or successful authentication.
In Account → API keys, use the Permissions plus control to add the intended permission entry, complete that entry, then check the expiry below the rate limits before saving. The section heading alone does not grant a scope. Scroll back to Save API Key when every required field is complete.
The list name, saved record ID, displayed key prefix and full secret serve different purposes. Name identifies the consumer; the prefix helps recognize the credential without exposing it; only the full secret can authenticate a new client. Do not paste the short table prefix into an integration's secret field.
3. Save the one-time secret, not the table prefix
The success panel shows API Key Created Successfully and the full returned secret. Copy it privately before dismissing the panel. Then inspect the saved key row.
The creation panel contains the usable secret. The table keeps a prefix for identification; its reveal and copy controls don't recover the full key.
The table's current copy handler copies keyPrefix followed by an ellipsis. That string cannot authenticate. If the full secret was lost, replace/regenerate the disposable key through the appropriate operation; don't repeatedly paste the prefix into a client.
Do not place the secret in Build Studio HTML, a browser bundle, a screenshot or a shared script. This is a practical part of using this server credential, not an extra public-client setup step.
4. Authenticate through the current AppEngine endpoint
The explicit authentication controller uses:
<configuredAPPENGINEThe returned object includes user information, API-key identity/scopes and a token. Keep the token private. Confirm the returned key identity and organization before using it for a controlled request.
Follow these steps
In a private API client, set the actual base URL and those headers, send the request once, and inspect the status and returned identity without exposing credentials. Then use the read endpoint supplied by your integration’s API contract for a known disposable record. BusinessMade does not expose the Appmint Database → API & Endpoints menu in this route; do not look for that menu here. Your organization’s developer can obtain the request in Appmint Studio if needed. Use the supported authentication returned by this flow, then compare the returned record ID and value with BusinessMade → Tools → Data explorer. A successful authentication response alone does not prove that record read.
The organization header chooses the context, and the full key authenticates the connector. This response identifies our key. Now we'll read the same training record we can identify in BusinessMade.
The explicit auth controller reads x-api-key; do not assume a Bearer example from a different guard has the same contract. Keep global API prefixes from the configured base URL intact. Record not-found, wrong-organization and authentication failures separately.
5. Verify limits and permission boundaries
Test a wrong organization ID in a separate controlled authentication attempt; it should not authenticate the same organization-owned key. Test a key you have deliberately expired or removed only in the training environment and inspect the actual rejection.
The authentication service checks the key hash, active state, expiry and its rate limits. It returns the saved scopes, but the inspected guard/authentication code does not itself enforce each endpoint's requested scope. Therefore test an intended read and a disallowed write against a disposable record using this key's identity. A selected read:data badge is not proof that writing is blocked.
We'll check both the operation this integration should perform and one it should not. The configuration tells us the intent; the response tells us what the current application enforces.
If the write unexpectedly succeeds, record an authorization finding and keep restricted integration deployment blocked until corrected and retested. Do not present the course as a security guarantee or widen scopes to hide a failing contract. Use small controlled limits for a rate-limit rehearsal; avoid unnecessary requests.
6. Inspect usage and last-used information
Return to API Keys and refresh/reload. Match the key's name/prefix, Last Used and daily usage information with the controlled request. Daily usage shows recorded requests against the configured per-day value. No data is distinct from zero usage.
This information helps identify which credential the connector used. Check the timing and actual response; a delayed or unavailable usage lookup doesn't tell you the request failed.
The frontend loads usage separately from the key list. Usage totals may refresh separately; check their timestamp before relying on them.
7. Regenerate or replace a key
Explain the choice before the operation. Regenerate API Key replaces the secret/hash for the same key record. It is not a second independently valid key or a promised overlap period. On a disposable key, select Regenerate, privately copy the new secret, update the client and test authentication. Attempt the old full secret again and inspect its rejection.
Regenerate changes the credential this record accepts. I'll update the test connector and verify the new secret, then confirm the old one no longer authenticates.
For a live connector needing a controlled migration, create a separately named replacement key, test it, update dependent clients, then retire the old key. This lets you verify the replacement before removing the old credential. Authentication tokens already issued from a key have their own lifecycle; neither regeneration nor deletion alone proves every previously issued token is revoked. Test that boundary where required.
The current page invokes regeneration directly from its action button. Do not promise an additional confirmation prompt.
8. Delete a key and understand the admin revoke route
Choose Delete API Key only on the disposable retired record after checking its name and consumer. Reload the list and repeat authentication with the removed secret. Confirm the intended connector now uses its replacement.
The standard page exposes Delete and Regenerate, not a Revoke button. The administrative API uses POST /api-key/admin/revoke/:keyId. The local frontend service now targets that exact controller route; a mocked request-contract regression verifies its POST method and key ID. No key was revoked in this documentation pass. An authorized administrator using the API must still verify the changed status and rejected authentication; the local route correction does not establish revocation of previously issued tokens.
You now know where to create a named integration credential, which value to save, how to check the organization and actual request, and how to replace or remove it. Keep the intended scopes and the observed access result separate until both agree.
Limitations and checks
Reviewed: web account/api-keys.tsx, hooks/use-api-keys.tsx, services/apikey-api.service.ts, endpoint map; AppEngine users/apikey.controller.ts, apikey.service.ts, auth/apikey.auth.guard.ts.
Remaining: live key lifecycle and controlled read/write enforcement, exact consumer endpoint authentication, usage timing, rate-limit response, expiry boundary and issued-token lifecycle. No secrets were created or exposed, no keys were regenerated/deleted, and no live request is claimed by this draft.
BusinessMade routing and outcome check
The menu and route were checked in packages/ui/src/ui/sidebars/business-made-links.ts and apps/business-made/src/shell/route-registry.ts. Open the module through the route stated at the start, perform the controlled procedure, save, reopen and inspect its actual BusinessMade consumer. Do not infer branch isolation from a header location selection when this shared screen reads organization-wide records. Record any access refusal or consumer mismatch with the exact record identity. No new provider, payment, physical-device or live-tenant action was performed for this adaptation.