Term definitions

Authentication. The process of verifying the identity of the user or the app. To keep solar workflows on our platform secure, Aurora expects all apps authenticate when making API requests.

Authorization. The process of giving permissions to apps. Admin users can authorize Aurora apps to access data in a tenant. For example, an app might be authorized to retrieve roof summary and racking array details.

Embedded app. Your embedded app will have two components: a frontend component embedded into Aurora and a backend component that’s responsible for syncing data with Aurora.

Backend app. You can build an Aurora app without a frontend component. For example, your app might retrieve project summary data from Aurora and post site survey results without the need for UI in Aurora.

Types of authentication methods

The authentication methods you will use depend on the type of your app.

Embedded apps

Embedded apps use application key + session token + temporary key.

Application key

An application key grants you access to request a temporary key for each tenant that has authorized your app. Application keys cannot be used directly with the Sync or Design APIs. A production application key along with your application_id will be issued to you on successful app review by Aurora.

Session token

Session tokens verify that a customer user performed the action and adds an extra layer of security. The tokens are required for embedded apps, expire after one hour and may only be used for a single key exchange.

A typical key exchange flow is as follows:

1. Your frontend app receives a request from Aurora that includes the aurora_session_token query parameter.
2. Your app makes a request to retrieve a temporary key using the application key and the session token.

Temporary key

A temporary key gives you access to select Sync and Design API endpoints in a customer tenant. Temporary keys are only valid for 13 hours. We recommend retrieving a new temporary key each time your app is loaded.

You can retrieve the temporary key by providing your application key as a bearer token via the Authorization header and session token via the session_token query parameter.

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"
    }
}

Backend apps

Backend apps use application key + temporary key.

Application key

An application key grants you access to request a temporary key for each tenant that our mutual customers authorized your app for. Application keys cannot be used directly with the Sync or Design APIs. A production application key along with your application_id will be issued to you on successful app review by Aurora.

Temporary key

A temporary key gives you access to select Sync and Design API endpoints in a customer tenant. Temporary keys are only valid for 13 hours.

You can retrieve the temporary key by providing your application key as a bearer token via the Authorization header.

curl -X POST \
  -H "Authorization: Bearer {your application key}" \
"https://api-sandbox.aurorasolar.com/partner_applications/{application_id}/tenants/{aurora_tenant_id}/create_token'
    "token": {
        "bearer_token": "tk_test_fd1cc8562360ff06b6e524aa",
        "expires_at": "2023-07-29 04:30:46 UTC"
    }
}

Authorization flow

Admin users can authorize your app to access data in their tenant.

Your embedded app can self-generate a temporary key for the tenant every time you receive a request from Aurora.

Your backend app can self-generate a temporary key at will.