Apps - Onyx Documentation

Apps give Craft controlled, authenticated access to external services. Admins configure Apps under Admin Panel → Craft → Apps. Users connect their accounts under Craft → Apps.

Craft Apps are different from Onyx connectors. A connector indexes shared content into Onyx knowledge. An App retrieves live information from a user’s external account and can take actions in that service.

Choose the setup path

App type	Organization configuration	User connection
Built-in on Onyx Cloud	Onyx manages the OAuth client. Admins enable the App and set action policies.	Each user completes the provider’s OAuth flow.
Built-in on self-hosted Onyx	An admin creates an OAuth application with the provider, then enters its client ID and secret in Onyx.	Each user completes the provider’s OAuth flow.
Custom App	An admin defines public URL patterns, authentication headers, credentials, and an instruction bundle.	Users enter any credential values not supplied by the organization.

Onyx currently provides built-in Apps for Slack, Google Calendar, Google Drive, Gmail, Linear, GitHub, HubSpot, and Notion. One organization-level instance of each built-in provider can be configured. You can create multiple custom Apps with different slugs and URL patterns.

Configure a built-in App

On Onyx Cloud, built-in Apps are provided by Onyx. Select Edit to configure permissions, then enable the App from its card. For self-hosted Onyx, first create an OAuth application with the external provider. Use this exact redirect URI, replacing the host with your Onyx domain:

https://onyx.example.com/craft/v1/apps/oauth/callback

The scheme, host, and path must match exactly in the provider and Onyx. The App management form asks for the OAuth client ID and client secret; it does not ask for an individual user’s access token.

On self-hosted Onyx, the callback host comes from WEB_DOMAIN. Confirm that setting uses the public domain registered with the provider before users connect.

Slack

Create a Slack app and add the Onyx redirect URI under OAuth & Permissions. Add these User Token Scopes:

channels:history
channels:read
chat:write
files:write
groups:history
groups:read
im:history
im:read
im:write
search:read
users:read

Craft acts with a user token; no bot user is required. Copy the Client ID and Client Secret from the Slack app’s basic information.

Google Calendar

In Google Cloud Console, create or select a project, enable the Google Calendar API, configure the OAuth consent screen, and create an OAuth 2.0 Client ID of type Web application. Add the Onyx redirect URI under Authorized redirect URIs. Craft requests full Google Calendar access.

Google Drive

In Google Cloud Console, enable both the Google Drive API and Google Docs API, configure the OAuth consent screen, and create an OAuth 2.0 Web application client with the Onyx redirect URI. Craft requests the full Drive scope so it can read, create, edit, and delete files; action policies govern those operations inside Craft.

Gmail

In Google Cloud Console, enable the Gmail API, configure the OAuth consent screen, and create an OAuth 2.0 Web application client with the Onyx redirect URI. Craft requests gmail.modify, which covers reading, labels, drafts, trash, and sending but not permanent message deletion.

Linear

In Linear, open Settings → API → OAuth applications, create an OAuth application, and add the Onyx redirect URI to its callback URLs. Craft requests user-acting read and write access for issues, projects, and comments.

GitHub

In GitHub, open Settings → Developer settings → OAuth Apps, create an OAuth App, and use the Onyx redirect URI as its authorization callback URL. Craft requests repo, read:org, and read:user; the repo scope includes repositories the connecting user can access, including private repositories.

HubSpot

From a HubSpot developer account, create an app and add the Onyx redirect URI on its Auth tab. Configure read access for owners, contacts, companies, and deals. Contact, company, and deal write scopes are optional so read-only HubSpot accounts can still connect.

Notion

Create a Public integration from Notion’s integrations settings and add the Onyx redirect URI under OAuth Domain & URIs. Choose the integration’s read and write capabilities in Notion; Notion controls capabilities there rather than through OAuth scopes.

Add and test the App

Open App management

Go to Admin Panel → Craft → Apps. Select a provider under Available apps or Add another. On Onyx Cloud, open the App configured by Onyx.

Enter organization credentials

On self-hosted Onyx, enter the OAuth client ID and client secret from the provider. On Onyx Cloud, these fields are managed by Onyx and are not shown.

Review permissions

Choose a policy for all actions, or open Advanced and set policies action by action. Review every write, send, delete, and publish action.

Enable the App

Save the configuration and confirm the App card says Enabled. Disabled Apps do not appear to users and cannot inject credentials.

Test as a user

Connect a pilot user’s account from Craft → Apps. Test a read and a representative write, confirm the approval card is understandable, and verify the result in the external service.

Set action policies

Built-in Apps define a catalog of recognizable actions. Each action has one organization-wide policy:

Policy	Runtime behavior	Typical use
Auto-approve	Craft performs the action without pausing for the user.	Narrow, low-risk reads and non-consequential preparation.
Ask	Craft pauses before the request and shows the user an approval card.	Sends, creates, edits, broad reads, and other changes.
Deny	The proxy blocks the action. The user cannot override it.	Destructive, unsupported, or prohibited operations.

The built-in catalog starts with curated defaults: many reads are Auto-approved, while consequential changes generally use Ask. Do not assume the default is right for your organization; review the action list when enabling each App. The main permissions selector applies Auto-approve or Ask to every action. Open Advanced to create a mixed policy or choose Deny for individual actions.

If one outbound request matches more than one action, the strictest matching policy wins: Deny, then Ask, then Auto-approve. A request to a built-in App that does not match a cataloged action falls back to Ask.

An in-session Approve for session decision applies only to matching actions in that session. It does not change the admin policy and cannot override Deny.

Scheduled Tasks and pre-approval

A Scheduled Task runs without a user present. Its owner can select required Apps under Pre-approved Apps. For that task’s running sessions, the selection allows Ask actions from the entire App to proceed without a live approval. Pre-approval does not override Deny. Because it applies to the App rather than one action, keep both the task prompt and its App list narrow. Onyx creates a notification when a Scheduled Task uses a pre-approved action.

Create a custom App

Use a custom App for a publicly reachable HTTP API that is not covered by a built-in provider. A custom App combines proxy configuration with a ZIP bundle that teaches Craft how to call the API.

Field	Purpose
Name and description	Identifies the App to users and explains when it should be used.
Upstream URL patterns	Limits which outbound request URLs belong to the App.
Header credential pattern	Defines headers the proxy injects, with placeholders such as `{api_key}`.
Organization credentials	Supplies placeholder values shared by every user. Values left unspecified must be entered by each user.
Bundle	Provides `SKILL.md` instructions, examples, scripts, and helper files for calling the API.

For example:

Setting	Value
Upstream URL pattern	`https://api.example.com/v1/*`
Header	`Authorization`
Header value	`Bearer {api_key}`
Organization credential	`api_key` = a shared service token, or leave it blank for users to supply individually

Define URL patterns narrowly

Custom Apps use URL globs. Each pattern must start with http:// or https://, and its host must be literal. Wildcards are allowed only after the host.

# Recommended: one HTTPS host and a narrow path
https://api.example.com/v1/reports/*

# Too broad: every path on the host
https://api.example.com/*

# Invalid: wildcard in the host
https://*.example.com/*

Custom Apps cannot be used to reach private, loopback, link-local, cloud metadata, or other non-public network addresses. The sandbox proxy blocks internal destinations even when a URL pattern includes them. Expose only a deliberately secured, publicly routable HTTPS endpoint if Craft must call a custom service.

Avoid overlapping URL patterns between Apps. When more than one App claims the same URL, the lowest-ID App—usually the earliest created—is selected first. A disabled App can still claim the match before credential availability is checked, so do not rely on enablement to disambiguate overlapping patterns.

Configure credentials

In a header value, write each credential as a named placeholder:

Authorization: Bearer {api_key}
X-Workspace-ID: {workspace_id}

Add a value under Organization credentials when every user should use the same service identity. Leave a placeholder without an organization value when each user should enter their own value on the Apps page. You can also leave the header pattern empty for a public API that requires no credential. Raw organization and user credentials are encrypted in Onyx-controlled storage. They are not copied into the custom bundle or sandbox workspace. After a request passes its gate, the sandbox proxy injects the rendered headers on the way out.

Prepare the instruction bundle

The bundle uses the same structure and validation rules as a custom Skill:

example-api.zip
├── SKILL.md
├── examples/
│   └── request.json
└── scripts/
    └── example_api.py

The ZIP filename becomes the App slug. Put a valid SKILL.md at the root and review every included file. The default limits are 25 MB per extracted file and 100 MB for the complete bundle. See Managing Craft Skills for the bundle format and review checklist.

Custom Apps do not have a per-action catalog. For a connected custom App, every request matching an upstream URL pattern is treated as an unspecified Ask action. Admins cannot Auto-approve or Deny individual custom App operations. Disable the App to stop its use, and be especially cautious when users pre-approve it for a Scheduled Task.

Manage credentials and lifecycle

Action	Effect
Edit	Updates policies or, when admin-managed, the name, OAuth credentials, custom URL patterns, headers, credentials, or bundle.
Disable	Hides the App from users and stops credential injection while retaining its configuration and user connections.
Enable	Makes the App available again. Existing user grants are reused if they remain valid.
Delete	Permanently removes the App configuration, user credential records, policies, and Scheduled Task pre-approval references.

Onyx-managed Cloud Apps cannot be deleted and their OAuth configuration cannot be edited by Admins. Disable them when they should not be available.

Troubleshooting

A built-in App connection fails

Confirm the OAuth client ID and secret, the exact redirect URI, the enabled API or integration capabilities, and the required scopes. Check whether the provider’s consent screen is limited to approved test users or workspace members.

An enabled App does not appear to users

Confirm that its card says Enabled and that the user has Craft access. Refresh the Apps page. For a custom App, confirm its bundle and configuration saved successfully.

A user connected successfully but an action is blocked

Check the action’s admin policy and the scopes or capabilities granted by the external account. A Deny policy cannot be overridden. An Ask request can also fail if the user rejects it or the approval expires.

A custom App prompts for every request

This is expected. Custom Apps use one synthesized Ask action for every request matching their URL patterns. They do not currently support per-action policies.

A custom App calls the wrong service or uses the wrong credential

Check for overlapping URL patterns. Make every host and path as specific as possible. The lowest-ID App wins when multiple Apps match the same URL, including when that first App is disabled.

A Scheduled Task is awaiting approval

Confirm that the task owner is still connected to the App and selected it under Pre-approved Apps. Then check for a Deny policy or a different App than the prompt was expected to use. Correct the task and use Run now; the blocked run does not resume automatically.

Apps for users

Show users how to connect accounts, guide Craft, and review approvals.

Craft Architecture

Review egress controls, credential injection, and approval enforcement.

​Choose the setup path

​Configure a built-in App

​Add and test the App

​Set action policies

​Scheduled Tasks and pre-approval

​Create a custom App

​Define URL patterns narrowly

​Configure credentials

​Prepare the instruction bundle

​Manage credentials and lifecycle

​Troubleshooting

Apps for users

Craft Architecture

Choose the setup path

Configure a built-in App

Add and test the App

Set action policies

Scheduled Tasks and pre-approval

Create a custom App

Define URL patterns narrowly

Configure credentials

Prepare the instruction bundle

Manage credentials and lifecycle

Troubleshooting