Rowan Docs

Integrating Rowan Into a User-Facing Platform

Rowan provides API-first access to hosted molecular simulation, property prediction, and structure-based molecular design tools. This post is a high-level guide for building a Rowan integration into your user-facing platform.

Rowan currently integrates with Edison, muni, Mirror, K-Dense, Vicena, and others. Learn more about how we support agentic science on our agentic science landing page.

For more detailed information about our Python API/SDK, see our Python API documentation.

Agent integrations

Rowan provides a prepackaged computational chemistry and biology agent skill for agentic platforms. Install the skill in your platform's agent to help it choose appropriate Rowan workflows and write Python SDK scripts that run those workflows for end users.

Rowan's data model

Rowan organizes data into a few basic levels:

  • An organization contains many users.
  • A user can own or access many projects.
  • A project holds a top-level folder and can be shared between users.
  • A folder holds workflows as well as nested subfolders (folders can be nested to any depth).

Projects provide the primary security boundary for integrations serving multiple end users.

API keys

Standard API keys have one of three access levels:

  • Read, write, and delete
  • Read and write
  • Read only

A key can also be scoped to a single project. Project-scoped keys cannot access data outside that project, even if their owner has access to other projects.

Master API keys

A master API key can create and manage other API keys. This lets a trusted backend create projects and issue project-scoped keys programmatically.

Never give an agent or end-user environment a master API key—or any key that can access another end user's projects. Keep the master key in your trusted backend and give each agent/user only the project-scoped key it needs.

For more information, see our documentation page about API keys. You can create and manage your account's API keys here: https://labs.rowansci.com/account/api-keys.

API key lifecycle and storage

Treat every Rowan API key as a secret:

  • Give session keys the shortest practical expiration by setting valid_days. A session key should not remain valid long after its session ends.
  • The plaintext key is returned only when the key is created and cannot be retrieved later. Plan for a one-time handoff to your secrets manager or the intended runtime; if the key is lost, revoke it and create a replacement.
  • Store keys in a secrets manager, not in plaintext in your application database unless your architecture requires it. If a database must hold a key, encrypt it at rest and tightly restrict access.
  • Never log keys. Scrub them from request logs, error reports, traces, and debugging output.
  • Revoke a key when its user, session, or integration is terminated. Expiration is a backstop, not a substitute for revocation.
  • Rotate long-lived keys regularly by creating a replacement, updating consumers, and then revoking the old key.

Integration patterns

One Rowan user per platform user

Each end user of your platform receives a corresponding Rowan user. These users can all belong to your platform's Rowan organization, allowing billing and access to be managed centrally.

This is the most direct one-to-one model. It works well for deep integrations, particularly when users should also be able to log into Rowan to inspect their workflows and results.

This configuration requires custom setup. Contact contact@rowansci.com to get started.

One Rowan project per platform user

A central Rowan user owns the integration. Your backend creates a separate Rowan project and project-scoped API key for each end user.

This keeps each user's data isolated while allowing the platform to manage billing and infrastructure through a single Rowan account. It works well when users return over time and should retain access to their previous calculations.

One Rowan project per platform session

A central Rowan user creates a new Rowan project and project-scoped API key for each session or run.

This works well for autonomous research agents and other run-based systems. For example, a ten-hour research run can receive its own isolated project, with the key revoked when the run ends.

This model offers stronger separation between individual runs and makes it easy to archive or delete them independently.

Creating project-scoped API keys programmatically

The project-per-user and project-per-session patterns can be implemented using a master API key:

import rowan

project = rowan.create_project(name=f"platform-session-{session_id}")

created_key = rowan.create_api_key(
    name=f"platform-session-{session_id}",
    scope="read_write",
    valid_days=1,
    scoped_project_uuid=project.uuid,
)

session_api_key = created_key.key

Pass session_api_key to the isolated runtime, keep the master key in your backend, and revoke the scoped key when it is no longer needed.

Keeping your integration responsive

Rowan workflows run asynchronously, so your application does not need to hold a user-facing request open while a calculation runs. Submit the workflow, return its identifier to your client, and handle completion outside the request path.

The Python API supports several patterns:

  • Pass webhook_url when submitting a workflow to have Rowan send a POST request when it completes. Verify incoming requests using the X-Rowan-Signature header and rowan.verify_webhook_secret.
  • Use workflow.done() or workflow.get_status() for non-blocking status checks from a background worker.
  • Call workflow.result(wait=False) to return immediately with the data currently available. Use workflow.result() when blocking is appropriate, or workflow.stream_result() to consume partial results while polling.

Data retention and deletion

Revoking an API key prevents future use of that credential, but it does not delete the projects, workflows, or results the key previously accessed. Access control and data retention should therefore be handled as separate lifecycle steps.

Data is retained until a customer requests deletion. Organization customers may request automatic data-deletion policies for time-limited retention.

To remove stored workflow data, retrieve the workflow and call workflow.delete_data(). To delete the workflow itself, call workflow.delete(). Project and folder objects also expose delete() methods when you need to remove those records. Apply these operations according to your retention policy when a user, session, or integration is terminated.