Aptly SDK Reference

The Aptly SDK is loaded via a single script tag and populates window.aptly. See Building Embedded Apps for the getting started guide.

API reference

Property / method	Type	Description
`aptly.token`	`string \| null`	Current delegate token
`aptly.org`	`{ id, name }`	Logged-in user’s organization
`aptly.user`	`{ id, email, firstName, lastName, phone, role, teams }`	Logged-in user. `role` is an array of role names assigned to the user in this org. `teams` is an array of team IDs the user belongs to.
`aptly.config`	`object`	Admin-declared config variables, fully merged across all active scopes. See Config scoping.
`aptly.board`	`{ id, schema } \| null`	Board context — only present when the app is embedded as a board tab. `schema` is the board’s field schema.
`aptly.fetch(path, options?)`	`Promise<Response>`	Auth-aware fetch. Prepends the Aptly API base URL (`https://core-api.getaptly.com`). Automatically retries once on `401` with a fresh token. Returns a standard `Response`.
`aptly.requestToken()`	`Promise<string>`	Force-refresh the delegate token and return the new value. Normally not needed — `aptly.fetch` handles token refresh automatically.
`aptly.startEmulation(token, opts?)`	`Promise<window.aptly>`	Verify a GA-issued dev token against the Aptly API, resolve real user/org identity, and populate `window.aptly` as if Aptly had delivered context. `opts.config` overrides config values; `opts.org` overrides org fields. Returns `window.aptly`.
Embed actions — open a dialog in Aptly for the user to complete, require admin-granted permission per embed
`aptly.actions`	`string[]`	List of embed action IDs the current embed has been granted. Check this at runtime before calling an action method. Example: `['start-dialer', 'create-card']`.
`aptly.action(id, payload)`	`Promise<{ success: boolean, error?: string }>`	Generic embed action dispatcher. Useful when the action ID is dynamic. Times out after 3 seconds. See Embed App Actions.
`aptly.openCardPane({ cardId })`	`Promise<{ success, error? }>`	Open a card in the board side panel. Requires `open-card-pane` action permission.
`aptly.openCardView({ cardId })`	`Promise<{ success, error? }>`	Open a card in a fullscreen modal. Requires `open-card-view` action permission.
`aptly.startDialer({ number, name? })`	`Promise<{ success, error? }>`	Open the phone dialer pre-filled. `number` must be E.164 format. Requires `start-dialer` permission.
`aptly.openEmailComposer({ subject?, content?, composeMode? })`	`Promise<{ success, error? }>`	Open the email/SMS composer pre-filled. `composeMode` defaults to `'email'`. Requires `open-email-composer` permission.
`aptly.createEvent({ date?, comments?, recipients? })`	`Promise<{ success, error? }>`	Open the calendar event editor pre-filled. Requires `create-event` permission.
`aptly.createCard({ boardId, fields? })`	`Promise<{ success, error? }>`	Open the new card form on a specific board. Requires `create-card` permission.
`aptly.createTask({ title?, dueAt?, priority?, ... })`	`Promise<{ success, error? }>`	Open the task creation form pre-filled. Requires `create-task` permission.
`aptly.createContact({ firstname?, lastname?, email?, ... })`	`Promise<{ success, error? }>`	Open the contact creation modal pre-filled. Requires `create-contact` permission.
`aptly.navigateToContact({ contactId })`	`Promise<{ success, error? }>`	Navigate to a contact’s record page. Requires `navigate-to-contact` permission.

Config scoping

aptly.config always contains the fully merged configuration for the current context — app devs just read aptly.config.YOUR_KEY without knowing which scope a value came from. Admins set a contextScope on each app that controls how config values are stored:

Scope	Where values are stored	Use case
`company` (default)	One record per org per app	All users and boards share the same config
`board`	One record per board per app	Different config per board — e.g. each board uses its own data source ID
`user`	One record per user per app	Personal settings that don’t affect teammates
`all`	All three levels simultaneously	Maximum flexibility — user settings override board settings override company settings

Merge priority: user > board > company. If the same key is set at multiple levels, the narrowest scope wins.

// Same code regardless of what scope the admin chose
const boardId = aptly.config.LEASES_BOARD_ID;

Configuring board-scoped apps: Users configure board-scoped apps directly in the board view settings panel, where the board context is known. Company and user-scoped apps are configured in the app store.

URL params (Option C dev testing)

Append any of these to your app’s URL to simulate Aptly context with no code changes:

Param	Sets
`aptly_token`	`aptly.token`
`aptly_config_KEY`	`aptly.config.KEY` (any key name)
`aptly_org_id`	`aptly.org.id`
`aptly_org_name`	`aptly.org.name`
`aptly_user_id`	`aptly.user.id`
`aptly_user_email`	`aptly.user.email`
`aptly_user_first_name`	`aptly.user.firstName`
`aptly_user_last_name`	`aptly.user.lastName`

Example:

https://your-app.repl.co?aptly_token=MY_TOKEN&aptly_config_BOARD_ID=lease&aptly_org_name=Acme

When running inside Aptly, URL params are ignored — the real postMessage context takes priority.

Getting Started

Guides

Reference

Aptly SDK Reference

API reference

Config scoping

URL params (Option C dev testing)

​API reference

​Config scoping

​URL params (Option C dev testing)

API reference

Config scoping

URL params (Option C dev testing)