📘

Private beta

• Beta product features will not be supported via our normal support channels (e.g., email).
• You may experience some gaps or changes as the product is refined and documentation updated.
• There may be some compatibility issues between our beta and generally available product.

How it Works

Aurora users can select a “Design Mode Extension” from a dropdown list in app. Similar to a Google Chrome extension, design mode extensions allow you to bring your custom functionality to Aurora.

After selecting your extension, Aurora will load your app in an iframe and pass key data to your app as query parameters. Your app can leverage this information to access the Sync API and retrieve Aurora data. Extensions can be either fullscreen, which take up the entire screen, or split-screen, which allow you to see both your extension and Aurora design mode at the same time.

Example Extension App

To learn more about how design mode extensions work, you can enable the Aurora API Client app on the “Apps” settings page. The API Client is a split-screen app which allows you to easily interact with the Aurora API and see detailed data about the project and design you’re currently viewing. While the example app only queries certain APIs, your app can leverage any Aurora’s Sync API to implement a wide variety of functionality.

Getting Started

This tutorial assumes you have already been provisioned a sandbox account to become familiar with Aurora. To get started developing in Aurora, you’ll first need an app with a public URL for Aurora to iframe. When setting up your app, read over the embedded apps page for best practices and considerations on how your app will be framed.

One Time Setup

Please provide the following to your Aurora account team:

• Your app name
• A tagline for your app to display on the “Apps” page (256 characters or less)
• A description for your app to display to users at enablement
• A logo image for your app (scaled to 44px height)
• The iframe URL for your app
• Whether your extension should be fullscreen or split-screen

In return, Aurora will provide you with:

• an application_id for your app
• an application key to access the partner app API
• Aurora will enable your app on your sandbox tenant

Step 1: Parse query parameters

On each load of your app, Aurora will send the following URL query parameters:

• tenant_id, as aurora_tenant_id
• user_id, as aurora_user_id
• project_id, as aurora_project_id
• design_id, as aurora_design_id
• session_token, as aurora_session_token

Step 2: Generate a temporary token

Aurora uses an “OAuth-like” flow to secure partner app access. For more information, see Authorization: embedded apps.

Using the aurora_session_token value from the query parameters, your application_id and your application key provided by Aurora, make a request to generate a new temporary key. To avoid exposing your application key, this request should always happen server-side.

curl -X POST \
  -H "Authorization: Bearer {your application key}" \
	"https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/tenants/{aurora_tenant_id}/create_token?session_token={aurora_session_token}"

{
  "token": {
    "bearer_token": "tk_test_fd1cc8562360ff06b6e524aa",
    "expires_at": "2023-07-29 04:30:46 UTC"
  }
}

Step 3: Access the Aurora Sync API

Using the Aurora ids provided to the iframe, lookup key attributes of the Aurora project or design using the Sync API. These requests will use the temporary key you retrieved in step 2 for authentication.

curl -X GET \
  -H "Authorization: Bearer {temporary key}" \
  "https://api.aurorasolar.com/<any Sync API path>"

Note that some resources may be nested, and you may need to call a “List …” endpoint to find the resource that interests you most.

Develop your App

Once you’ve successfully made calls to the Sync API, you should be able to develop your app to your use cases. Explore the Sync API docs to find endpoints that you need to complete your app.

Considerations

• For development, Aurora will give you access to all API endpoints. Before releasing your app for general use, Aurora will limit your app to only access scopes it needs in order to protect customer data.
• If you need to change your app name or iframe URL during development, you may use the app config API.