> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amps.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Link UI

> Six-step auth at auth.amps.ai/{appId}: device-type, OEM, credentials (username/password, API key, OAuth2), MFA, device select, and consent.

## Overview

The Link UI is the hosted authentication flow your end users open to connect their OEM devices. It runs OEM selection, credential capture, MFA, device selection, and consent in a single sequence so your application never handles OEM credentials directly.

## Link UI URLs

The Link UI uses the same base URL for both Sandbox and Live environments. The environment is determined by a query parameter.

**Base URL:**

```
https://auth.amps.ai/{appId}
```

**Sandbox Environment:**

```
https://auth.amps.ai/{appId}?sandbox=true
```

**Live Environment:**

```
https://auth.amps.ai/{appId}
```

The `sandbox` query parameter accepts `true` or `1` to enable sandbox mode. If omitted, the environment defaults to Live.

<Note>
  Replace `{appId}` with your actual application ID from the dashboard.
</Note>

<Card title="Environments Guide" icon="info" href="/get-started/environments">
  Learn more about Sandbox and Live environments
</Card>

## Authentication Flow

<Steps>
  <Step title="Device Type Selection">
    Users first select the type of device they want to connect (e.g., Vehicle, Solar Inverter, Battery, HVAC, etc.)

    <Frame>
      <img src="https://mintcdn.com/ampsai/0nXXb16E_PzfRg-N/images/link-ui-step-1.png?fit=max&auto=format&n=0nXXb16E_PzfRg-N&q=85&s=5db6a90eeffcef8eb82dde65e12e6745" alt="Link UI step 1: Device type selection screen" width="1440" height="1280" data-path="images/link-ui-step-1.png" />
    </Frame>
  </Step>

  <Step title="OEM Selection">
    Users select which OEM they want to connect (e.g., Tesla, Enphase, Nest, etc.)

    <Frame>
      <img src="https://mintcdn.com/ampsai/0nXXb16E_PzfRg-N/images/link-ui-step-2.png?fit=max&auto=format&n=0nXXb16E_PzfRg-N&q=85&s=fe7d379b340a70b0036dd7c177ca5299" alt="Link UI step 2: OEM selection screen" width="1440" height="1280" data-path="images/link-ui-step-2.png" />
    </Frame>
  </Step>

  <Step title="Credential Authentication">
    Users authenticate using one of three methods supported by the OEM:

    * **Username/Password**: Traditional login credentials
    * **API Key**: OEM-provided API key
    * **OAuth2**: OAuth flow for supported OEMs

    <Frame>
      <img src="https://mintcdn.com/ampsai/0nXXb16E_PzfRg-N/images/link-ui-step-3.png?fit=max&auto=format&n=0nXXb16E_PzfRg-N&q=85&s=e207e704c4f73b279640e56dd1ddd3ee" alt="Link UI step 3: Credential entry screen" width="1440" height="1280" data-path="images/link-ui-step-3.png" />
    </Frame>
  </Step>

  <Step title="Multi-Factor Authentication">
    If required by the OEM, users complete MFA verification
  </Step>

  <Step title="Device Selection">
    Users select which devices they want to connect from their OEM account
  </Step>

  <Step title="Consent & Registration">
    Users grant permissions and devices are registered to your customer account
  </Step>
</Steps>

## Connection Types

Different OEMs support different authentication methods:

<ResponseField name="username_password" type="string">
  Traditional username and password authentication. Users enter their OEM account credentials directly.
</ResponseField>

<ResponseField name="api_key" type="string">
  API key-based authentication. Users provide an API key issued by the OEM.
</ResponseField>

<ResponseField name="oauth2" type="string">
  OAuth 2.0 flow for supported OEMs. Users are redirected to the OEM's authorization page.
</ResponseField>

## Integration Options

<CardGroup cols={2}>
  <Card title="Direct Link" icon="external-link">
    Direct users to the Link UI URL. After completion, they'll be redirected back to your application.
  </Card>

  <Card title="Embedded Flow" icon="window-maximize">
    Embed the Link UI in an iframe within your application (if supported).
  </Card>
</CardGroup>

## What Happens After Connection

Once devices are connected:

1. **Device Registration**: Devices are registered to your customer account
2. **Immediate Access**: You can immediately query device data via the API
3. **Webhook Notifications**: You'll receive `device.connected` webhook events
4. **Device Management**: Devices appear in your dashboard and can be managed via API

## Security & Privacy

<Tip>
  The Link UI handles all credential storage securely. Credentials are encrypted and stored separately from your application.
</Tip>

* Credentials are never exposed to your application
* All authentication happens directly with the OEM
* Users maintain full control over their device connections
* Users can disconnect devices at any time

## Reconnection Flow

Users can reconnect devices without re-entering credentials, as long as their credentials remain valid with the OEM.

<AccordionGroup>
  <Accordion title="When does reconnection happen?">
    Reconnection occurs when:

    * A user wants to add more devices from the same OEM
    * Credentials need to be refreshed
    * Device connection status needs to be verified
  </Accordion>

  <Accordion title="What if credentials are invalid?">
    If credentials are no longer valid, users will be prompted to re-authenticate through the full connection flow.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="User can't find their OEM">
    Ensure the OEM is supported in your environment. Some OEMs may only be available in sandbox or live environments.
  </Accordion>

  <Accordion title="Authentication keeps failing">
    Verify that:

    * The OEM credentials are correct
    * MFA is completed if required
    * The OEM account has proper permissions
    * The OEM service is not experiencing outages
  </Accordion>

  <Accordion title="Devices not showing up">
    Check that:

    * The OEM account has devices registered
    * Device permissions are granted during consent
    * The device type is supported by Amps AI
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Link UI Customization" icon="settings" href="/guides/link-ui/customization">
    Learn about advanced configuration options
  </Card>

  <Card title="API Authentication" icon="key" href="/get-started/authentication">
    Learn how to authenticate your API requests
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks/receive">
    Set up webhook endpoints
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore the full API documentation
  </Card>
</CardGroup>