Copy page

Advanced Topics

Permissions

Permissions control what your app can access on the Teachfloor platform.

Overview

Permissions control three types of access:

1. Contextual Data: Data the platform includes in event callbacks (course, module, element)
2. Storage & Features: Platform features your app can use (data storage, AI generation)
3. Public API: Endpoints your app's servers can call via OAuth (api.teachfloor.com/v0/*) — see OAuth for the full mapping.

All permissions must be declared in your app manifest with a user-facing explanation.

How Permissions Work

Permissions are enforced on two surfaces:

• SDK — when your app subscribes to events, the platform includes an objectContext parameter containing contextual data based on your granted permissions. For example, with courses:read permission, objectContext.course includes the current course data when in a course viewport.
• Public API — when your app opts into OAuth, a subset of permissions is minted into the access token as OAuth scopes, unlocking the matching endpoints on api.teachfloor.com/v0/*. See OAuth for details.

Some permissions apply to both surfaces (e.g. courses:read grants SDK context AND GET /v0/courses/*); others are surface-specific (e.g. members:read is API-only, appdata:read is SDK-only).

Available Permissions

Your app can request the following permissions:

Contextual Data Permissions

Permission	Description	Access Type
user:read	Access user profile information	User data in objectContext
user_events:read	Access user activity events	User events
courses:read	Access course contextual data	Course object in objectContext
modules:read	Access module contextual data	Module object in objectContext
elements:read	Access element contextual data	Element object in objectContext

Storage Permissions

Permission	Description	Access Type	Hierarchy
appdata:read	Read organization-wide app data	Storage API - App Data	Read only
appdata:write	Write organization-wide app data	Storage API - App Data	Includes read
userdata:read	Read user-specific app data	Storage API - User Data	Read only
userdata:write	Write user-specific app data	Storage API - User Data	Includes read
usercollection:read	Read user data collections	Storage API - Collections	Read only
usercollection:write	Write to user data collections	Storage API - Collections	Includes read

AI & Feature Permissions

Permission	Description	Access Type
ai:text_generate	Generate text using AI models	AI Generation API
ai:context_external_send	Send platform data to AI models	AI Context Sharing

Realtime Permissions

Permission	Description	Access Type
realtime	Publish and subscribe to the app's realtime channels	Realtime SDK

Public API Permissions

These permissions grant your app's servers access to the Teachfloor public API via the OAuth token. They are not available through the SDK — only your backend can use them by calling https://api.teachfloor.com/v0/* with the app's access token.

Permission	Description	Access Type
members:read	Read organization members and their course enrollments	Public API only
activities:read	Read activity records generated by members	Public API only

Permission Details

User Permissions

user:read

Access basic user profile information.

Data available in objectContext:

• User ID
• Full name
• Email address
• Avatar URL
• Language preference
• Timezone

Use cases:

• Personalization
• User greetings
• Profile displays

Example:

Code
{
  "permission": "user:read",
  "purpose": "Display personalized greetings and user information"
}

user_events:read

Access user activity and learning events.

Data available in objectContext:

• Course enrollments
• Module completions
• Element interactions
• Login history
• Activity timestamps

Use cases:

• Progress tracking
• Analytics dashboards
• Activity feeds
• Engagement metrics

Example:

Code
{
  "permission": "user_events:read",
  "purpose": "Track learning progress and generate activity reports"
}

Contextual Permissions

These permissions control what data appears in the objectContext parameter based on the current viewport.

courses:read

Access course information when user is in a course viewport.

Data available in objectContext.course:

• Course ID
• Course title
• Description
• Status
• Enrollment data
• Course settings

Available in viewports:

• teachfloor.dashboard.course.detail
• teachfloor.dashboard.course.module.detail
• teachfloor.dashboard.course.element.detail

Example:

Code
{
  "permission": "courses:read",
  "purpose": "Display course information in notes and widgets"
}

Usage:

Code
import { subscribeToEvent } from '@teachfloor/extension-kit'

subscribeToEvent('environment.viewport.changed', (viewport, objectContext) => {
  if (objectContext.course) {
    console.log('Course title:', objectContext.course.name)
    console.log('Course ID:', objectContext.course.id)
  }
})

modules:read

Access module information when user is viewing a module.

Data available in objectContext.module:

• Module ID
• Module title
• Description
• Order/sequence
• Completion status

Available in viewports:

• teachfloor.dashboard.course.module.detail
• teachfloor.dashboard.course.element.detail

Example:

Code
{
  "permission": "modules:read",
  "purpose": "Show module progress and navigation"
}

Usage:

Code
import { subscribeToEvent } from '@teachfloor/extension-kit'

subscribeToEvent('environment.viewport.changed', (viewport, objectContext) => {
  if (objectContext.module) {
    console.log('Module title:', objectContext.module.name)
    console.log('Module order:', objectContext.module.position)
  }
})

elements:read

Access learning element information when user is viewing an element.

Data available in objectContext.element:

• Element ID
• Element type (video, assignment, quiz, etc.)
• Title and description
• Content metadata
• Completion status

Available in viewports:

• teachfloor.dashboard.course.element.detail

Example:

Code
{
  "permission": "elements:read",
  "purpose": "Display element information and add notes to content"
}

Usage:

Code
import { subscribeToEvent } from '@teachfloor/extension-kit'

subscribeToEvent('environment.viewport.changed', (viewport, objectContext) => {
  if (objectContext.element) {
    console.log('Element type:', objectContext.element.type)
    console.log('Element title:', objectContext.element.name)
    console.log('Completed:', objectContext.element.completed)
  }
})

Storage Permissions

Storage permissions allow your app to persist data on the Teachfloor platform. See Data Storage for detailed usage.

appdata:read & appdata:write

Store and retrieve organization-wide app data shared across all users.

Use cases:

• App configuration
• Global settings
• Shared templates
• Feature flags

Example (Read and Write):

Code
{
  "permissions": [
    {
      "permission": "appdata:write",
      "purpose": "Save and load app configuration and shared settings"
    }
  ]
}

Example (Read-Only):

Code
{
  "permissions": [
    {
      "permission": "appdata:read",
      "purpose": "Load app configuration and shared settings"
    }
  ]
}

Usage:

Code
import { store, retrieve } from '@teachfloor/extension-kit'

// Write app data
await store('config', { theme: 'dark', lang: 'en' }, 'appdata')

// Read app data
const config = await retrieve('config', 'appdata')

userdata:read & userdata:write

Store and retrieve user-specific data.

Permission Hierarchy: userdata:write includes userdata:read access.

Use cases:

• User preferences
• Personal settings
• User state
• Draft content

Example (Read and Write):

Code
{
  "permissions": [
    {
      "permission": "userdata:write",
      "purpose": "Save and load your personal preferences and settings"
    }
  ]
}

Example (Read-Only):

Code
{
  "permissions": [
    {
      "permission": "userdata:read",
      "purpose": "Load your personal preferences and settings"
    }
  ]
}

Usage:

Code
import { store, retrieve } from '@teachfloor/extension-kit'

// Write user data
await store('preferences', { theme: 'light', fontSize: 14 }, 'userdata')

// Read user data
const prefs = await retrieve('preferences', 'userdata')

usercollection:read & usercollection:write

Store and retrieve collections of data items for a user, with pagination support.

Use cases:

• Activity logs
• User notes or annotations
• Saved items
• History data

Example (Read and Write):

Code
{
  "permissions": [
    {
      "permission": "usercollection:write",
      "purpose": "Save and load your notes and activity history"
    }
  ]
}

Example (Read-Only):

Code
{
  "permissions": [
    {
      "permission": "usercollection:read",
      "purpose": "Load your saved notes and activity history"
    }
  ]
}

Usage:

Code
import { store, retrieve } from '@teachfloor/extension-kit'

// Add item to collection
await store('notes', {
  title: 'My Note',
  content: 'Content...',
  createdAt: Date.now()
}, 'usercollection')

// Retrieve collection with pagination
const result = await retrieve('notes?limit=10', 'usercollection')
console.log(result.data) // Array of items
console.log(result.next) // Next cursor

AI Permissions

ai:text_generate

Generate text using AI language models.

Use cases:

• Content generation
• Text completion
• Summarization
• Translation

Example:

Code
{
  "permission": "ai:text_generate",
  "purpose": "Generate content suggestions and summaries"
}

Usage:

Code
import { generate } from '@teachfloor/extension-kit'

// Generate text using AI
const result = await generate(
  'Write a summary of this course',
  'ai/text-generate'
)

console.log(result) // Generated text response

ai:context_external_send

Permission to use platform data placeholders in AI prompts.

How it works: This permission is only checked when you use placeholders like {{course.name}} or {{module.content}} in your AI prompts. Without this permission, you can still use generate() with regular prompts.

Supported Placeholders:

• {{course.name}} - Course title
• {{course.content}} - Course content (text format)
• {{module.name}} - Module title
• {{module.content}} - Module content (text format)
• {{element.name}} - Element title
• {{element.content}} - Element content (text format)

Example:

Code
{
  "permissions": [
    {
      "permission": "ai:text_generate",
      "purpose": "Generate content suggestions"
    },
    {
      "permission": "courses:read",
      "purpose": "Access course information"
    },
    {
      "permission": "ai:context_external_send",
      "purpose": "Include course content in AI prompts"
    }
  ]
}

Usage:

Code
import { generate } from '@teachfloor/extension-kit'

// Without placeholders - only needs ai:text_generate
const simpleResult = await generate('Write a motivational message')

// With placeholders - needs ai:text_generate + ai:context_external_send + courses:read
const contextResult = await generate(
  'Summarize this course: {{course.content}}'
)

// Multiple placeholders
const detailedResult = await generate(
  'Create a quiz about {{module.name}} covering: {{module.content}}'
)

Realtime Permission

realtime

Publish and subscribe to your app's realtime channels. Enables sub-second event delivery between an app's SDK views (widgets, drawers, pages) while learners are active.

Use cases:

• Live collaboration UIs (cursors, presence, live-edit)
• Broadcasting state changes from one widget instance to others
• Instructor-side dashboards that react to learner activity in real time

Example:

Code
{
  "permission": "realtime",
  "purpose": "Broadcast live collaboration cursors between learners viewing this widget"
}

Usage:

Code
import { realtime, useExtensionContext } from '@teachfloor/extension-kit'

const courseId = useExtensionContext().environment.context.course?.id

// Subscribe to a course-scoped channel and receive events other
// clients publish on it.
const channel = realtime.subscribe({ scope: 'course', id: courseId })
channel.on('cursor.moved', (message) => renderRemoteCursor(message.data))

// Broadcast to every other subscriber on the same channel.
channel.publish('cursor.moved', { x: 120, y: 340 })

Subscribing to a course-scoped channel additionally needs courses:read (and the same pattern for modules:read / elements:read) — without it, the host strips the resource id from the viewport payload and there's no id to subscribe with. See Realtime Channels for the full channel model, event shape, and delivery guarantees.

Public API Permissions

These permissions apply only to server-to-server calls via the app's OAuth token — they don't expose data through the SDK. Your app needs to opt into OAuth (see OAuth) for them to have any effect.

members:read

Read organization members and their course enrollments via the public API.

Grants access to:

• GET /v0/members — list all members
• GET /v0/members/search — search members
• GET /v0/members/{id} — fetch a specific member
• GET /v0/members/{id}/courses — list a member's course enrollments (requires courses:read)
• GET /v0/courses/{id}/members — list members enrolled in a course (requires courses:read)
• GET /v0/courses/{id}/members/{member_id} — fetch a specific enrollment (requires courses:read)

Use cases:

• Sync members into an external CRM or HR system
• Reporting on enrollment across your customer base

Example:

Code
{
  "permission": "members:read",
  "purpose": "Sync course enrollments to our HR system"
}

activities:read

Read activity records generated by members interacting with course elements.

Grants access to:

• GET /v0/activities — list all activities
• GET /v0/activities/{id} — fetch a specific activity
• GET /v0/elements/{id}/activities — list activities for a given element (requires elements:read)

Use cases:

• Feed learner progress into an external analytics dashboard
• Trigger downstream automations when specific activity types occur

Example:

Code
{
  "permission": "activities:read",
  "purpose": "Export completion data to our LMS reporting tool"
}

Permission Management

Adding Permissions

Using CLI

Code
teachfloor apps grant permission

Select permission and enter purpose when prompted.

Manual Addition

Edit teachfloor-app.json:

Code
{
  "permissions": [
    {
      "permission": "courses:read",
      "purpose": "Display course information in widgets"
    },
    {
      "permission": "user_events:read",
      "purpose": "Track your learning progress"
    }
  ]
}

Removing Permissions

Using CLI

Code
teachfloor apps revoke permission

Manual Removal

Remove from manifest:

Code
{
  "permissions": [
    // Remove the permission object you no longer need
  ]
}

Permission Purposes

Each permission must have a clear, user-facing explanation.

Good purposes:

• "Display course information in your notes" ✓
• "Show your current module progress" ✓
• "Track your learning progress for analytics" ✓

Poor purposes:

• "Access data" ✗ (too vague)
• "Platform integration" ✗ (not user-facing)
• "Required for functionality" ✗ (not specific)

Using Permissions

Always check if contextual data exists before accessing it:

Code
import { subscribeToEvent } from '@teachfloor/extension-kit'

subscribeToEvent('environment.viewport.changed', (viewport, objectContext) => {
  // Check before accessing
  if (objectContext.course) {
    console.log('Course:', objectContext.course.name)
  }

  // Use optional chaining
  const moduleTitle = objectContext.module?.title || 'No module'
})

Next Steps

→ Continue to Deployment

Additional Resources

• Integration Guide - Using permissions with events and storage
• Best Practices - Permission best practices and patterns
• Examples - Complete permission usage examples