API Reference

This section provides a detailed API reference for all public classes, methods, and functions in the frameio-kit library.

frameio_kit

Classes:

• App –

  The main application class for building Frame.io integrations.

• SecretResolver –

  Protocol for app-level secret resolution.

• Client –

  Asynchronous HTTP client for interacting with the Frame.io v4 API.

• Account –

  Represents the account context, used in standard webhook payloads.

• ActionEvent –

  A custom action event payload, including user-submitted form data.

• Project –

  Represents the project context in which an event occurred.

• Resource –

  Represents the primary resource that an event pertains to.

• User –

  Represents the user who initiated the event.

• WebhookEvent –

  A standard webhook event payload from Frame.io.

• Workspace –

  Represents the workspace (formerly Team) in which an event occurred.

• Middleware –

  Base class for creating middleware in Frame.io integrations.

• OAuthConfig –

  OAuth configuration for Adobe IMS authentication.

• CheckboxField –

  A checkbox input.

• Form –

  A modal with a form to collect input from the user.

• LinkField –

  A non-editable field that displays a URL with a "Copy" button.

• Message –

  A simple message modal to display information to the user.

• SelectField –

  A dropdown menu allowing the user to select one from a list of options.

• SelectOption –

  Represents a single choice within a SelectField.

• TextareaField –

  A multi-line text input area, suitable for longer descriptions.

• TextField –

  A single-line text input field.

Functions:

• get_user_token –

  Get the authenticated user's access token.

• verify_signature –

  Verifies the HMAC-SHA256 signature of an incoming Frame.io request.

Attributes:

• AnyEvent –

  Union type representing any event that can be processed by the app.

• NextFunc –

  Type alias for the next function in the middleware chain.

• AnyResponse –

  Union type representing any response that can be returned from handlers.

AnyEvent module-attribute

AnyEvent = ActionEvent | WebhookEvent

Union type representing any event that can be processed by the app.

NextFunc module-attribute

NextFunc = Callable[[AnyEvent], Awaitable[AnyResponse]]

Type alias for the next function in the middleware chain.

AnyResponse module-attribute

AnyResponse = Message | Form | None

Union type representing any response that can be returned from handlers.

App

App(
    *,
    token: str | None = None,
    middleware: list[Middleware] = [],
    oauth: OAuthConfig | None = None,
    secret_resolver: SecretResolver | None = None,
)

The main application class for building Frame.io integrations.

This class serves as the core of your integration. It is an ASGI-compatible application that listens for incoming HTTP POST requests from Frame.io, validates their signatures, and dispatches them to the appropriate handler functions that you register using decorators.

Attributes:

• client (Client) –

  An authenticated API client for making calls back to the Frame.io API, available if an token was provided.

Parameters:

• token

  (str | None, default: None ) –

  An optional access token obtained from the Adobe Developer Console. If provided, this token will be used to authenticate API calls made via the app.client property. It is highly recommended to load this from a secure source, such as an environment variable.

• middleware

  (list[Middleware], default: [] ) –

  An optional list of middleware classes to process requests before they reach the handler.

• oauth

  (OAuthConfig | None, default: None ) –

  Optional OAuth configuration for user authentication. When provided, enables Adobe Login OAuth flow for actions that require user-specific authentication.

• secret_resolver

  (SecretResolver | None, default: None ) –

  Optional app-level secret resolver that implements the SecretResolver protocol. Provides dynamic secret resolution for webhooks and actions. Falls back to environment variables if not provided.

Methods:

• on_webhook –

  Decorator to register a function as a webhook event handler.

• on_action –

  Decorator to register a function as a custom action handler.

• __call__ –

  ASGI call interface to delegate to the underlying Starlette app.

client property

client: Client

Provides access to an authenticated asynchronous API client.

This client can be used within your handler functions to make calls back to the Frame.io API to fetch more information or perform actions. The client is initialized lazily on its first access.

Example

@app.on_webhook("file.ready", secret="...")
async def on_file_ready(event: WebhookEvent):
    # Use the client to fetch more details about the file
    file_details = await app.client.files.show(account_id=event.account_id, file_id=event.resource_id)
    print(file_details.data.name)

Returns:

• Client –

  An instance of Frame.io Client, ready to make authenticated requests.

Raises:

• RuntimeError –

  If the App was initialized without an token.

token_manager property

token_manager: TokenManager

Provides access to the OAuth token manager.

This manager handles encrypted token storage, retrieval, and automatic refresh for user authentication. Only available when OAuth is configured.

Example

# Delete a user's token (logout)
await app.token_manager.delete_token(user_id="user_123")

# Check if user has a token
token = await app.token_manager.get_token(user_id="user_123")
if token:
    print("User is authenticated")

Returns:

• TokenManager –

  The TokenManager instance for managing user tokens.

Raises:

• RuntimeError –

  If OAuth was not configured during App initialization.

on_webhook

on_webhook(
    event_type: str | list[str],
    secret: str | WebhookSecretResolver | None = None,
)

Decorator to register a function as a webhook event handler.

This decorator registers an asynchronous function to be called whenever Frame.io sends a webhook event of the specified type(s). A webhook handler can only receive WebhookEvent and can only return a Message or None.

Example

from frameio_kit import App, WebhookEvent

app = App()

# Using explicit secret string
@app.on_webhook(event_type="file.ready", secret="your-secret")
async def on_file_ready(event: WebhookEvent):
    pass

# Using decorator-level resolver
async def resolve_secret(event: WebhookEvent) -> str:
    return await db.get_secret(event.account_id)

@app.on_webhook(event_type="file.ready", secret=resolve_secret)
async def on_file_ready(event: WebhookEvent):
    pass

# Using WEBHOOK_SECRET environment variable
@app.on_webhook(event_type="file.ready")
async def on_another_event(event: WebhookEvent):
    pass

Parameters:

• event_type

  (str | list[str]) –

  The Frame.io event type to listen for (e.g., "file.ready"). You can also provide a list of strings to register the same handler for multiple event types.

• secret

  (str | WebhookSecretResolver | None, default: None ) –

  The signing secret or a resolver function. Can be: - A string: Static secret for signature verification - A callable: Async function receiving WebhookEvent and returning secret - None: Falls back to app-level resolver or WEBHOOK_SECRET env var

Raises:

• ValueError –

  If no secret source is available (no explicit secret, no app-level resolver, and no WEBHOOK_SECRET environment variable).

on_action

on_action(
    event_type: str,
    name: str,
    description: str,
    secret: str | ActionSecretResolver | None = None,
    *,
    require_user_auth: bool = False,
)

Decorator to register a function as a custom action handler.

This decorator connects an asynchronous function to a Custom Action in the Frame.io UI. The handler receives an ActionEvent and can return a Message, a Form for more input, or None.

Example

from frameio_kit import App, ActionEvent

app = App()

# Using explicit secret string
@app.on_action(event_type="my_app.transcribe", name="Transcribe", description="Transcribe file", secret="your-secret")
async def on_transcribe(event: ActionEvent):
    pass

# Using decorator-level resolver
async def resolve_secret(event: ActionEvent) -> str:
    return await db.get_secret(event.resource.id)

@app.on_action(event_type="my_app.convert", name="Convert", description="Convert file", secret=resolve_secret)
async def on_convert(event: ActionEvent):
    pass

# Using CUSTOM_ACTION_SECRET environment variable
@app.on_action(event_type="my_app.process", name="Process", description="Process file")
async def on_process(event: ActionEvent):
    pass

Parameters:

• event_type

  (str) –

  A unique string you define to identify this action (e.g., "my_app.transcribe"). This is the type that will be present in the incoming payload.

• name

  (str) –

  The user-visible name for the action in the Frame.io UI menu.

• description

  (str) –

  A short, user-visible description of what the action does.

• secret

  (str | ActionSecretResolver | None, default: None ) –

  The signing secret or a resolver function. Can be: - A string: Static secret for signature verification - A callable: Async function receiving ActionEvent and returning secret - None: Falls back to app-level resolver or CUSTOM_ACTION_SECRET env var

• require_user_auth

  (bool, default: False ) –

  If True, requires user to authenticate via Adobe Login OAuth before executing the handler. OAuth must be configured in App initialization for this to work.

Raises:

• ValueError –

  If no secret source is available (no explicit secret, no app-level resolver, and no CUSTOM_ACTION_SECRET environment variable).

__call__ async

__call__(scope: Scope, receive: Receive, send: Send)

ASGI call interface to delegate to the underlying Starlette app.

SecretResolver

Bases: Protocol

Protocol for app-level secret resolution.

Implement this protocol to provide dynamic secret resolution for both webhooks and actions. Each method receives the specific event type it handles, allowing for context-aware secret lookup (e.g., from a database).

Example

class DatabaseSecretResolver:
    def __init__(self, db):
        self.db = db

    async def get_webhook_secret(self, event: WebhookEvent) -> str:
        return await self.db.webhooks.get_secret(event.account_id)

    async def get_action_secret(self, event: ActionEvent) -> str:
        return await self.db.actions.get_secret(event.resource.id)

resolver = DatabaseSecretResolver(db)
app = App(secret_resolver=resolver)

Methods:

• get_webhook_secret –

  Resolve secret for webhook events.

• get_action_secret –

  Resolve secret for action events.

get_webhook_secret async

get_webhook_secret(event: WebhookEvent) -> str

Resolve secret for webhook events.

Parameters:

• event

  (WebhookEvent) –

  The webhook event being processed.

Returns:

• str –

  The secret to use for signature verification.

get_action_secret async

get_action_secret(event: ActionEvent) -> str

Resolve secret for action events.

Parameters:

• event

  (ActionEvent) –

  The action event being processed.

Returns:

• str –

  The secret to use for signature verification.

Client

Client(
    *,
    base_url: str | None = None,
    token: str | Callable[[], str] | None = None,
    headers: dict[str, str] | None = None,
    timeout: float | None = None,
    follow_redirects: bool | None = True,
)

Bases: AsyncFrameio

Asynchronous HTTP client for interacting with the Frame.io v4 API.

This class provides access to all stable API endpoints and also contains a dedicated client for experimental features via the .experimental property.

Attributes:

• experimental –

  An instance of ExperimentalFrameioClient for accessing endpoints that are in beta or under development.

Methods:

• close –

  Gracefully closes the underlying httpx.AsyncClient session.

close async

close() -> None

Gracefully closes the underlying httpx.AsyncClient session.

Account

Bases: BaseModel

Represents the account context, used in standard webhook payloads.

Attributes:

• id (str) –

  The unique identifier (UUID) of the account.

ActionEvent

Bases: _BaseEvent

A custom action event payload, including user-submitted form data.

This model is used for handlers registered with @app.on_action. It differs from WebhookEvent by having a top-level account_id and including specific fields related to the action's lifecycle.

Attributes:

• account_id (str) –

  The ID of the account where the event originated.

• action_id (str) –

  The ID of the custom action that was triggered.

• interaction_id (str) –

  A unique ID for a sequence of interactions, used to correlate steps in a multi-step custom action (e.g., a form submission).

• data (dict[str, Any] | None) –

  A dictionary containing submitted form data. This will be None for the initial trigger of an action before a form is displayed. When a form is submitted, the keys of this dictionary will match the name of each form field.

resource_id property

resource_id: str

A convenience property to directly access the resource's ID.

Returns:

• str –

  The unique identifier (UUID) of the event's primary resource.

user_id property

user_id: str

A convenience property to directly access the user's ID.

Returns:

• str –

  The unique identifier (UUID) of the user.

project_id property

project_id: str

A convenience property to directly access the project's ID.

Returns:

• str –

  The unique identifier (UUID) of the project.

workspace_id property

workspace_id: str

A convenience property to directly access the workspace's ID.

Returns:

• str –

  The unique identifier (UUID) of the workspace.

account property

account: Account

A convenience property to access the account as an Account object.

This provides consistency with WebhookEvent, allowing access to the account ID via event.account.id for both event types.

Returns:

• Account –

  An Account object containing the account ID.

Project

Bases: BaseModel

Represents the project context in which an event occurred.

Attributes:

• id (str) –

  The unique identifier (UUID) of the project.

Resource

Bases: BaseModel

Represents the primary resource that an event pertains to.

Attributes:

• id (str) –

  The unique identifier (UUID) of the resource.

• type (Literal['file', 'folder', 'version_stack']) –

  The type of the resource (e.g., 'file', 'folder').

User

Bases: BaseModel

Represents the user who initiated the event.

Attributes:

• id (str) –

  The unique identifier (UUID) of the user.

WebhookEvent

Bases: _BaseEvent

A standard webhook event payload from Frame.io.

This model is used for handlers registered with @app.on_webhook.

Attributes:

• account (Account) –

  The account context object for the event.

resource_id property

resource_id: str

A convenience property to directly access the resource's ID.

Returns:

• str –

  The unique identifier (UUID) of the event's primary resource.

user_id property

user_id: str

A convenience property to directly access the user's ID.

Returns:

• str –

  The unique identifier (UUID) of the user.

project_id property

project_id: str

A convenience property to directly access the project's ID.

Returns:

• str –

  The unique identifier (UUID) of the project.

workspace_id property

workspace_id: str

A convenience property to directly access the workspace's ID.

Returns:

• str –

  The unique identifier (UUID) of the workspace.

account_id property

account_id: str

A convenience property to directly access the account's ID.

Returns:

• str –

  The unique identifier (UUID) of the account.

Workspace

Bases: BaseModel

Represents the workspace (formerly Team) in which an event occurred.

Attributes:

• id (str) –

  The unique identifier (UUID) of the workspace.

Middleware

Base class for creating middleware in Frame.io integrations.

Middleware provides a powerful way to add cross-cutting concerns to your Frame.io integration without cluttering your handler functions. You can use middleware for logging, authentication, metrics collection, error handling, and more.

The Middleware base class provides three hooks you can override:

• __call__: The main entry point that runs for every event (both webhooks and actions)
• on_webhook: Runs only for webhook events
• on_action: Runs only for custom action events

Example

class TimingMiddleware(Middleware):
    async def __call__(self, event: AnyEvent, next: NextFunc) -> AnyResponse:
        start_time = time.monotonic()
        response = await next(event)
        duration = time.monotonic() - start_time
        print(f"Processed {event.type} in {duration:.2f}s")
        return response

app = App(middleware=[TimingMiddleware()])

Methods:

• __call__ –

  The main entry point that runs for every event (both webhooks and actions).

• on_webhook –

  Runs only for webhook events.

• on_action –

  Runs only for custom action events.

__call__ async

__call__(event: AnyEvent, next: NextFunc) -> AnyResponse

The main entry point that runs for every event (both webhooks and actions). This is where you implement logic that should apply universally.

Override this method when you need logic that should run on every single event, regardless of its type. This is perfect for universal concerns like:

• Request timing and performance monitoring
• Error handling and logging
• Authentication and authorization
• Request/response transformation

Parameters:

• event

  (AnyEvent) –

  The event being processed (WebhookEvent or ActionEvent)

• next

  (NextFunc) –

  Function to call the next middleware or handler in the chain

Returns:

• AnyResponse –

  The response from the next middleware or handler, or None

Example

async def __call__(self, event: AnyEvent, next: NextFunc) -> AnyResponse:
    # Code here runs before every event
    result = await next(event)  # Call the next middleware or handler
    # Code here runs after every event
    return result

Note

When you override __call__, you completely replace the base implementation. This means: - Without super(): The on_webhook and on_action methods will not be called - With super(): The original dispatch logic is preserved, so on_webhook and on_action will still be called

on_webhook async

on_webhook(
    event: WebhookEvent, next: NextFunc
) -> AnyResponse

Runs only for webhook events.

Override this method when you need webhook-specific logic that doesn't apply to custom actions.

Parameters:

• event

  (WebhookEvent) –

  The webhook event being processed

• next

  (NextFunc) –

  Function to call the next middleware or handler in the chain

Returns:

• AnyResponse –

  The response from the next middleware or handler, or None

Example

async def on_webhook(self, event: WebhookEvent, next: NextFunc) -> AnyResponse:
    # Code here runs only for webhook events
    result = await next(event)
    return result

on_action async

on_action(
    event: ActionEvent, next: NextFunc
) -> AnyResponse

Runs only for custom action events.

Override this method when you need action-specific logic that doesn't apply to webhooks.

Parameters:

• event

  (ActionEvent) –

  The action event being processed

• next

  (NextFunc) –

  Function to call the next middleware or handler in the chain

Returns:

• AnyResponse –

  The response from the next middleware or handler, or None

Example

async def on_action(self, event: ActionEvent, next: NextFunc) -> AnyResponse:
    # Code here runs only for action events
    result = await next(event)
    return result

OAuthConfig

Bases: BaseModel

OAuth configuration for Adobe IMS authentication.

This configuration is provided at the application level to enable user authentication via Adobe Login OAuth 2.0 flow.

Attributes:

• client_id (str) –

  Adobe IMS application client ID from Adobe Developer Console.

• client_secret (str) –

  Adobe IMS application client secret.

• base_url (str) –

  Base URL of your application (e.g., "https://myapp.com"). The OAuth callback will be automatically constructed as {base_url}/auth/callback and must be registered in Adobe Console.

• scopes (list[str]) –

  List of OAuth scopes to request. Defaults to Frame.io API access.

• storage (Optional[AsyncKeyValue]) –

  Storage backend instance for persisting encrypted tokens. If None, defaults to MemoryStore (in-memory, lost on restart).

• encryption_key (Optional[str]) –

  Optional encryption key. If None, uses environment variable or generates ephemeral key.

• token_refresh_buffer_seconds (int) –

  Number of seconds before token expiration to trigger automatic refresh. Defaults to 300 seconds (5 minutes). This prevents token expiration during ongoing API calls.

• http_client (Optional[AsyncClient]) –

  Optional httpx.AsyncClient for OAuth HTTP requests. If not provided, a new client will be created. Providing your own enables connection pooling, custom timeouts, and shared configuration.

Example

from frameio_kit import App, OAuthConfig
from key_value.aio.stores.disk import DiskStore
import httpx

# With custom HTTP client for connection pooling
custom_client = httpx.AsyncClient(timeout=60.0, limits=httpx.Limits(max_connections=100))

app = App(
    oauth=OAuthConfig(
        client_id=os.getenv("ADOBE_CLIENT_ID"),
        client_secret=os.getenv("ADOBE_CLIENT_SECRET"),
        base_url="https://myapp.com",
        storage=DiskStore(directory="./tokens"),
        token_refresh_buffer_seconds=600,  # Refresh 10 minutes early
        http_client=custom_client,  # Share connection pool
    )
)

redirect_uri property

redirect_uri: str

Construct the OAuth redirect URI from the base URL.

Returns:

• str –

  The full redirect URI (e.g., "https://myapp.com/auth/callback").

CheckboxField

Bases: _BaseField

A checkbox input.

Example:

from frameio_kit import Form, CheckboxField

return Form(
    title="Confirm Action",
    fields=[CheckboxField(label="Overwrite existing file?", name="overwrite", value=False)]
)

Attributes:

• type (Literal['checkbox']) –

  The field type, fixed to "checkbox".

• value (bool | None) –

  An optional default state for the checkbox (True for checked).

Form

Bases: _UIResponse

A modal with a form to collect input from the user.

When returned from a handler, this model renders a form in the Frame.io UI. Upon submission, Frame.io sends another ActionEvent to your endpoint, this time populating the data attribute with the user's input.

Attributes:

• fields (list[FormField]) –

  A list of one or more form field objects (e.g., TextField, SelectField) to be displayed in the form.

LinkField

Bases: _BaseField

A non-editable field that displays a URL with a "Copy" button.

This is useful for presenting a user with a link to an external resource that was generated as part of the action.

Example:

from frameio_kit import Form, LinkField

return Form(
    title="External Link",
    fields=[LinkField(label="External Link", name="external_link", value="https://www.example.com")]
)

Attributes:

• type (Literal['link']) –

  The field type, fixed to "link".

• value (str | None) –

  The URL to be displayed.

Message

Bases: _UIResponse

A simple message modal to display information to the user.

This is typically used as the final step in a custom action to confirm that an operation was successful or to provide information.

Example:

from frameio_kit import Message

return Message(title="Success", description="The action was successful.")

SelectField

Bases: _BaseField

A dropdown menu allowing the user to select one from a list of options.

Example:

from frameio_kit import Form, SelectField, SelectOption

PLATFORMS = [
    SelectOption(name="Twitter", value="twitter"),
    SelectOption(name="Instagram", value="instagram"),
]

return Form(
    title="Choose Platform",
    fields=[SelectField(label="Platform", name="platform", options=PLATFORMS)]
)

Attributes:

• type (Literal['select']) –

  The field type, fixed to "select".

• options (list[SelectOption]) –

  A list of SelectOption objects defining the choices.

• value (str | None) –

  An optional default value to pre-select an option. This must match the value of one of the items in the options list.

SelectOption

Bases: _BaseField

Represents a single choice within a SelectField.

Attributes:

• name (str) –

  The user-visible text for the option in the dropdown list.

• value (str) –

  The actual value that will be sent back in the data payload if this option is selected.

TextareaField

Bases: _BaseField

A multi-line text input area, suitable for longer descriptions.

Example:

from frameio_kit import Form, TextareaField

return Form(
    title="Comment",
    fields=[TextareaField(label="Comment", name="comment", value="Enter your feedback...")]
)

Attributes:

• type (Literal['textarea']) –

  The field type, fixed to "textarea".

• value (str | None) –

  An optional default value to pre-populate the field.

TextField

Bases: _BaseField

A single-line text input field.

Example:

from frameio_kit import Form, TextField

return Form(
    title="Comment",
    fields=[TextField(label="Comment", name="comment", value="Enter your feedback...")]
)

Attributes:

• type (Literal['text']) –

  The field type, fixed to "text".

• value (str | None) –

  An optional default value to pre-populate the field.

get_user_token

get_user_token() -> str

Get the authenticated user's access token.

This function retrieves the OAuth access token for the currently authenticated user. It can only be called within an action handler that has user authentication enabled (require_user_auth=True).

The token is stored in request-scoped context, not on the event object, to prevent accidental logging or exposure of sensitive credentials.

Returns:

• str –

  The user's OAuth access token string.

Raises:

• RuntimeError –

  If called outside a user-authenticated action context.

Example

from frameio_kit import App, get_user_token, Client

@app.on_action(..., require_user_auth=True)
async def process_file(event: ActionEvent):
    # Get the user's token
    token = get_user_token()

    # Use it with the built-in Client
    user_client = Client(token=token)

    # Or pass to other services
    await external_service.authenticate(token)

verify_signature async

verify_signature(
    headers: Headers, body: bytes, secret: str
) -> bool

Verifies the HMAC-SHA256 signature of an incoming Frame.io request.

This function is a critical security utility for validating that a webhook or custom action request genuinely originated from Frame.io and that its payload has not been tampered with. It should be called at the beginning of any request handler that receives events from Frame.io.

It validates the request by checking the timestamp to prevent replay attacks and by computing an HMAC-SHA256 signature from the request body and your unique secret, comparing it securely to the signature provided in the header.

Parameters:

• headers

  (Headers) –

  The incoming request headers, obtained directly from your web framework's request object (e.g., request.headers). This function expects to find 'X-Frameio-Request-Timestamp' and 'X-Frameio-Signature' headers.

• body

  (bytes) –

  The raw, unmodified request body as bytes, obtained directly from your web framework's request object (e.g., await request.body()). It is crucial that this is the raw body, not a parsed JSON object.

• secret

  (str) –

  The unique signing secret provided by Frame.io when you created the webhook or custom action. It's recommended to store this securely (e.g., as an environment variable).

Returns:

• bool –

  True if the signature is valid and the request is authentic.

• bool –

  False if the signature is invalid, the timestamp is too old, or

• bool –

  required headers are missing.