Managing Craft Apps and Approvals

Connect external apps, control credentials, and govern which actions Craft can take

Craft apps let sandboxes reach external services through the sandbox proxy. As an admin you decide which apps exist, how their credentials are supplied, which URLs they can reach, and which actions need approval before they run.

Manage apps from /craft/v1/apps/manage.

App types

Built-in app types are Slack, Google Calendar, Google Drive, Gmail, Linear, and GitHub. You can also create custom apps for internal or third-party services.

• Built-in apps ship with OAuth connection flows and a catalog of governable actions.
• Custom apps define their own URL patterns, credential fields, and skill instructions.

On Onyx Cloud, built-in apps use Onyx’s own OAuth credentials: you enable them and set policies but don’t supply client credentials. Self-hosted admins configure those themselves.

Add an app

1. Choose built-in or custom

   Use a built-in app where one fits, or build a custom app for an internal system.

2. Configure credentials

   Supply org-level OAuth or API settings where required, and decide which credentials users provide themselves.

3. Set action policies

   Start sensitive actions at Ask or Deny, and reserve Auto-approve for low-risk reads.

4. Test as a pilot user

   Connect as a pilot user, run a small session, and confirm approval cards carry enough detail to decide.

Credentials

Type	Used for
Organization credentials	Shared config such as OAuth client settings or service details.
User credentials	Per-user OAuth tokens, API tokens, or account-specific values.

Craft sandboxes never receive raw credentials. The sandbox sends placeholder values; the sandbox proxy injects the real credential only into an approved outbound request. See Craft Architecture.

Custom apps

A custom app defines:

Field	Purpose
Name and description	What users see in the Apps page and picker.
Upstream URL patterns	Which outbound URLs the proxy recognizes for the app. Keep them as narrow as the workflow allows.
Auth template	How credentials are inserted into matching outbound requests.
Organization and user credentials	Shared values admins supply, plus per-user values each user provides when connecting.
Skill bundle	Instructions and helper files Craft uses to call the app correctly.

Use custom apps for internal HTTP APIs, private SaaS, or anything no built-in app covers.

Action policies

Set a default policy per app and override individual actions.

Policy	Effect	Good default for
Auto-approve	Runs without prompting the user.	Low-risk reads and narrow internal lookups.
Ask	Pauses for the user before the request is sent.	Sends, edits, creates, calendar changes, and broad reads.
Deny	Blocks the action.	Deletes, sensitive systems, or unsupported workflows.

When a request matches several actions, the strictest policy wins: Deny, then Ask, then Auto-approve.

On Ask, the user gets an approval card and decides whether the action runs. The choices (Approve once, Approve for session, Reject) and how approvals expire are covered in Skills and Apps. Approve for session is scoped to that session and matching action types, not a permanent policy change.

Scheduled tasks and pre-approval

A Scheduled Task can store pre-approved app IDs so selected apps act during unattended runs. A Deny policy still overrides a pre-approval, and the approval is recorded as decided via pre-approval. Recommend it only when the prompt is narrow and the policy is already safe for unattended use. A run that hits an action still needing approval enters an awaiting approval state instead of completing.

Rotation and revocation

When a credential changes:

• Rotate organization credentials in the app configuration.
• Ask affected users to reconnect user-owned OAuth or credential fields.
• Re-test representative sessions and scheduled tasks.
• Tighten action policies while you investigate unexpected behavior.

Troubleshooting

Issue	What to check
App doesn’t appear to users	App enablement, group rollout, required org credentials, and user connection state.
Approval card lacks context	Action catalog, payload decoder, custom-app skill instructions, and URL pattern.
Request denied unexpectedly	Default policy, action override, URL match, missing credentials, or a stricter overlapping action.
Scheduled task awaiting approval	The task’s pre-approved app list and whether the action still has an Ask policy.