Documentation Index
Fetch the complete documentation index at: https://docs.getaptly.com/llms.txt
Use this file to discover all available pages before exploring further.
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. |
aptly.ui.openComposer(opts?) | void | Open the Aptly email/SMS composer in the parent window. opts: { to, subject, body, composeMode }. No-op with a console warning in dev/standalone mode. |
aptly.ui.createCard(boardId, fields) | void | Create a card on an Aptly board. boardId: board UUID. fields: { fieldKey: value } object. No-op in dev mode. |
aptly.ui.navigate(path) | void | Navigate the parent Aptly window to a path (e.g. '/inbox/mine'). No-op in dev mode. |
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 |
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;
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 |
https://your-app.repl.co?aptly_token=MY_TOKEN&aptly_config_BOARD_ID=lease&aptly_org_name=Acme