Developers Settings

​

Open Developers Settings

1. In the deck, open Settings.
2. Under System, choose Developers.

The breadcrumb reads Settings > System > Developers. You can also search for Developers in the command palette. Developers settings are scoped to the current entity. Confirm the entity selector before creating a key, reviewing logs, or downloading environment files. The page has a Test and Live mode toggle so admins can separate sandbox integration work from production integration work. The page always opens in Test mode. Only an entity owner or administrator sees the tabs. Anyone else sees an Access restricted page that reads “The Developer tab is available to entity owners and administrators only.” The page asks for settings.view to open, and the actions on it need the api_keys.manage_own permission on the server. Replaying an inbound webhook also needs settings.edit. The server refuses an action from a role without these, even when the button is shown. At the top of the page, Quick actions (Ctrl+K, or Cmd+K on a Mac) opens a short list: Create API key, View webhooks, View API logs, Open API documentation and a switch between Test and Live mode. Ctrl+N (Cmd+N) starts a new key while you are on the API Keys tab. Help opens the published API documentation in a new tab.

​

Understand the Developer Tabs

The tabs, in order, are API Keys, Webhooks, Inbound, Postman, API Logs, Analytics, Lens, Docs and SDKs.

• API Keys: create entity-scoped keys, filter by mode, search, review last use, inspect scopes, rotate when supported, revoke keys that should no longer work, and hide inactive keys from the default list.
• Webhooks: register HTTPS destinations that receive event notifications, choose subscribed event families, pause or resume delivery, reveal or rotate the signing secret, test active endpoints, and review delivery attempts.
• Inbound: check the health of the webhooks other services send to Arcus.
• Postman: download REST client collections and per-entity environment files for supported tools such as Postman, Bruno, and Insomnia.
• API Logs: review recent requests by status, date range, method, path, latency, IP address, request ID, and API key association.
• Analytics: review usage summaries, request trends, latency, error rate, top endpoints, and usage by key.
• Lens: turn on the read-only developer inspector.
• Docs: open the published API Docs, API Reference, and concept guides in a new tab.
• SDKs: see available language SDK entry points, install guidance, version notes, and links to SDK documentation.

​

Create an API Key Safely

An API key lets an external script, service, or integration authenticate against the current entity. Create keys only for named jobs with a known owner, known purpose, and narrow access.

1. Open the API Keys tab.
2. Confirm whether you are in Test or Live mode.
3. Select Create key. It opens the Create API key dialog, which Quick actions also opens.
4. Name the key after the job or system that will use it.
5. Choose the least access that will work: read-only, full access, or custom scopes.
6. Add elevated scopes only when the integration owner can explain why they are required.
7. Add an IP allowlist when the caller has stable outbound IP addresses.
8. Set an expiration date when the key is for a temporary migration, test, or vendor project.
9. Create the key, copy it once, and store it in a secret manager.

The create form has these boundaries:

• Key name is required.
• Mode is Test or Live.
• Read-only access grants read access across entity resources.
• Full access grants read and write access across entity resources.
• Custom scopes lets you choose read and write access for Orders, Products, Accounts, Inventory, Payments, and Accounting.
• Elevated scopes (optional) are Manage API keys, Migration write access, and Migration admin (cutover).
• Acknowledgement: a key that grants Full access or any elevated scope needs the acknowledgement box ticked before it can be created, because it can change or export this entity’s data. The Read-only access preset needs no acknowledgement.
• Audit Log: creating any key that grants Read-only access, Full access, or an elevated scope is recorded in the Audit Log with Critical severity. Other keys, such as one with only custom scopes, are recorded with Info severity.
• IP allowlist is optional, one entry per line, and supports CIDR notation.
• Expiration date is optional. Leaving it blank creates a key with no scheduled expiry.

​

Review and Revoke Keys

Review keys on a schedule. A clean key list should make it obvious which system owns each key, whether it is Test or Live, when it expires, when it was last used, and whether the scope still matches the job.

• Active-only view: focus on keys that can still authenticate.
• Mode filter: separate Test cleanup from Live production review.
• Last used: identify abandoned jobs, retired vendors, or broken integrations.
• Scope review: confirm keys are not broader than the current job requires.
• Rotate key: replace a key when an integration can be updated safely. The new token is shown once, and the old token keeps working for 24 hours.
• Revoke: disable keys for retired scripts, offboarded users, leaked secrets, or replaced integrations.
• Preview cleanup and Auto-cleanup: preview, then revoke, old throwaway keys. A key qualifies when its name starts with smoke-, debug-, audit-, API-VERIFY-, wave- or ext-test- and it is more than 24 hours old. Preview cleanup lists the keys that would be revoked (“Cleanup preview” with a count). Auto-cleanup revokes them and says “Revoked” with a count, or “No smoke keys to clean up”.

Choose a key’s row to open its detail, which shows its scopes and its IP restrictions (“No IP restrictions (all IPs allowed)” when there are none) and offers Rotate key and Revoke key. Revoking asks you to confirm in the Revoke API key dialog. Rotating shows the new token once in API Key Rotated. When the list is empty after a search the page says “No keys match your search”, with Clear search.

​

Key Messages

​

Register Webhooks Carefully

Webhooks notify an external system when Arcus events happen. Use them when another system needs near-real-time updates, such as order changes, invoice updates, payment results, inventory movement, fulfillment status, return status, connector state, or accounting activity.

1. Open the Webhooks tab.
2. Select Add endpoint.
3. Enter the HTTPS destination URL owned by the receiving system.
4. Add a short description that names the owner and purpose.
5. Select only the event families the receiver needs.
6. In the Add webhook endpoint dialog, select Add endpoint, then copy the signing secret according to the receiver’s setup process.
7. Send a test event when delivery infrastructure is available.
8. Review delivery history before assuming the receiving system is working.

Arcus requires an HTTPS URL and at least one selected event before a webhook can be created. The dialog is Add webhook endpoint, and the toast on success says the endpoint was created. Webhooks can be active, paused, or disabled. Pause and Resume switch delivery, with “Webhook paused” and “Webhook resumed”. Send test event works only on an active endpoint; on a paused one the page says “Resume the endpoint first to send test events.” A successful test says “Test event sent to endpoint”. The delivery list starts with “No deliveries yet. Send a test event to verify your endpoint.” The signing secret is hidden until you choose to reveal it. If it cannot be shown, the page says “Could not reveal signing secret. Try rotating the secret to generate a new one.” Delete asks you to confirm in the Delete webhook endpoint dialog and then says “Webhook deleted”. Each of pause, resume, rotate, test, create and delete is recorded in the Audit Log. An integration can also create and manage webhook endpoints through the public API with an API key, using the webhook endpoint actions documented in the API Reference.

​

Check Inbound Webhooks

The Inbound tab shows the webhooks that outside services send to Arcus, so you can see whether payments, carriers, stores, email, phones and banks are reaching you. The health cards show Processed 24h, Failed 24h, Last success and Last failure. Filter by source (Stripe, Shippo, Shopify, Postmark, RingCentral, Plaid or All sources) and by status (All statuses, Processed or Failed). The table lists Source, Event type, Status, Received and Event ID. Choose the eye icon to open Webhook event detail, with the event type, received and processed times, the payload, the request headers and any Processing error. With nothing received, the tab says “No webhook events yet”. If the event detail cannot load it says “Failed to load event” because the event may have been purged. Replay re-runs a stored event through the same handler that processed it the first time. It needs settings.edit. A replay can repeat the event’s effects, such as a payment update, a shipment status or a store order, so replay only an event whose first run failed, and read its processing error first. Arcus confirms with “Webhook replayed” and the resulting status, and records the replay in the Audit Log.

​

Use Lens

Lens is a read-only developer inspector docked at the bottom of every page. It shows the raw record behind whatever you are viewing, its related records, and the events and API requests that touched it. It never changes data. The Lens tab has Enable Lens, Auto-inspect (follow navigation and inspect the record on each page automatically; turn it off to pin the current record), a note about the keyboard shortcut to open or minimize it, and the list of inspectable records. Your choices are remembered. Using Lens needs the developer_tools.access permission, and without it the tab says “You do not have access to developer tools. Ask an owner or admin to grant the permission.”

​

Use Logs and Analytics for Troubleshooting

API Logs and Analytics are operator tools for finding integration health problems. They are not a replacement for the API Reference. Use them to answer what happened, when it happened, which key was involved, and whether failures are isolated or widespread.

• API Logs: filter by status (All statuses, 2xx Success, 4xx Client errors, 5xx Server errors) and by range (Last hour, Last 24 hours, Last 7 days). Choose a row to open Request detail, where Copy cURL command copies the request. Refresh reloads the list and Export CSV downloads it. With nothing to show the tab says “No logs found”.
• Analytics: compare request count, error rate, latency (P50, P95 and P99), active keys, endpoint usage, and usage by key over Last 24h, Last 7 days or Last 30 days. Export downloads the usage. With no requests the tab says “No API usage data”, and a failed download says “Export failed”.
• 4xx errors: usually indicate caller input, missing permission, expired key, revoked key, wrong mode, or wrong entity context.
• 5xx errors: usually need escalation with the request ID, time, key name or prefix, and affected workflow.
• High latency: compare endpoint trend, time window, and whether the issue affects one key or all keys.

​

Use Collections, Docs, and SDK Links

The Postman, Docs, and SDKs tabs help developers get to the right technical material without making the Help Center the source of API truth.

• Collections: download a REST client collection for a tool your team already uses.
• Environment files: Download environment (.json) gives the per-entity values with the entity ID already filled in. Paste the API key separately from a secure source. If no entity is selected the page says “No entity selected. Select an entity first.”
• Collection links: Copy URL copies the collection address. The page notes which version of the API specification the collection was generated from.
• Docs links: open API Docs, API Reference, webhooks, authentication, error handling, rate limits, idempotency, pagination, versioning, and SDK pages.
• SDKs: review which language SDKs are available now, which are coming soon, and where to find install or version details. The tab recommends pinning an API version, because a pinned version protects your integration from breaking changes during upgrades.

​

What Happens When You Act

• Keys: creating, rotating and revoking a key is recorded in the Audit Log. A revoked key stops authenticating at once. Rotating a key creates a new key with the same settings and keeps the old token working for 24 hours, so you have time to update the integration, then revokes it.
• Webhooks: creating, changing, pausing, rotating the secret of, testing and deleting an endpoint is recorded in the Audit Log. A test sends a real request to your destination.
• Replay: re-running an inbound event can update payments, shipments or store orders again.
• Other screens: key and webhook changes appear for other signed-in administrators without a reload.

​

Security Checklist

• Use one key per script, vendor, service, or integration job.
• Name keys so a future admin knows what owns them.
• Prefer Test mode until the integration is ready for production.
• Use the narrowest scope that completes the job.
• Use expirations for migrations, pilots, vendor setup, or temporary automation.
• Use IP allowlists when practical.
• Rotate or revoke keys after staff changes, vendor changes, suspected exposure, or job retirement.
• Never paste tokens, signing secrets, environment files, or private request payloads into support articles, screenshots, tickets, or chat.

​

Common Blocks

• Developers tab is missing or shows Access restricted: confirm your role is owner or admin and the entity has API access enabled.
• Lens tab says you do not have access: ask an owner or admin for the developer tools permission.
• Create API key is blocked: check your role, entity access, selected mode, and whether the requested scope is allowed for your user.
• A key works in Test but not Live: confirm the key was created in Live mode, the integration uses the Live base URL, and the entity is production-ready.
• Scope cannot be selected: choose a narrower preset or ask an owner to review permissions.
• Webhook test cannot be sent: confirm the endpoint is active and check whether delivery infrastructure is temporarily pending.
• No API logs appear: confirm requests are using the selected mode, date range, entity, and active key.
• Analytics are empty: make a valid request with the selected mode, then refresh after usage is recorded.

​

Related Articles