Skip to main content
The workspace settings schema defines the structure and types of the settings that users can configure for your app. This schema is used by experimental_useWorkspaceSettingsForm() to provide type-safe form components, ensuring that each component (like TextInput, NumberInput, or Toggle) can only reference fields with matching types in the schema (e.g., TextInput can only reference Settings.string() fields).
The Workspace Settings API is experimental and may change in the future. Please don’t use it in production versions of your app.

​
File Location

The settings schema must be defined in a file at src/app.settings.ts. This file location is required and cannot be changed.

​
Structure

app.settings.ts
import { Settings, type SettingsSchema } from "attio";

const appSettingsSchema = {
  workspace: {
    // Your workspace settings go here
  },
} satisfies SettingsSchema;

export default appSettingsSchema;
All settings are workspace-level, meaning they apply to the entire workspace where your app is installed.

​
Available Setting Types

The Settings object provides the following types:

​
Settings.string()

Defines a string setting. Use this for text values like names, URLs, or identifiers. 
workspace: {
  display_name: Settings.string(),
  webhook_url: Settings.string(),
  environment: Settings.string(),
}

​
Settings.boolean()

Defines a boolean setting. Use this for toggles, checkboxes, or on/off configurations. 
workspace: {
  auto_sync_enabled: Settings.boolean(),
  notifications_enabled: Settings.boolean(),
}

​
Settings.number()

Defines a numeric setting. Use this for counts, durations, or other numerical values. 
workspace: {
  sync_interval_minutes: Settings.number(),
  max_records_per_sync: Settings.number(),
  timeout_seconds: Settings.number(),
}

​
Complete Example

app.settings.ts
import { Settings, type SettingsSchema } from "attio";

const appSettingsSchema = {
  workspace: {
    display_name: Settings.string(),
    environment: Settings.string(),
    auto_sync_enabled: Settings.boolean(),
    sync_interval_minutes: Settings.number(),
    max_records_per_sync: Settings.number(),
    webhook_url: Settings.string(),
    notifications_enabled: Settings.boolean(),
    email_notifications: Settings.boolean(),
    default_assignee_id: Settings.string(),
    timeout_seconds: Settings.number(),
  },
} satisfies SettingsSchema;

export default appSettingsSchema;

​
Using the Schema

Once you’ve defined your schema, you can use it in your workspace settings form:
workspace-settings.tsx
import React from "react";
import { experimental_useWorkspaceSettingsForm, Section } from "attio/client";
import type { App } from "attio";

export const workspaceSettings: App.Settings.Workspace = {
  Page,
};

function Page() {
  const { 
    Form, 
    TextInput, 
    Toggle, 
    NumberInput 
  } = experimental_useWorkspaceSettingsForm();
  
  return (
    <Form>
      <Section title="General Settings">
        <TextInput label="Display name" name="display_name" />
        <TextInput label="Environment" name="environment" />
      </Section>
      
      <Section title="Sync Configuration">
        <Toggle 
          label="Enable automatic sync" 
          name="auto_sync_enabled" 
        />
        <NumberInput 
          label="Sync interval (minutes)" 
          name="sync_interval_minutes" 
        />
        <NumberInput 
          label="Max records per sync" 
          name="max_records_per_sync" 
        />
      </Section>
      
      <Section title="Webhook Settings">
        <TextInput 
          label="Webhook URL" 
          name="webhook_url" 
          type="url" 
        />
      </Section>
    </Form>
  );
}