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

# Introduction and Authentication

Components are fully-integrated, customisable UI building blocks that can be used
to build smart charging experiences within your app. They're built on top of Axle's
existing API and allow your customers to onboard their smart assets easily. Axle also provides
a pre-built "best-practice" smart charging app, which is designed to be embedded as a tab or seperate
page in an existing app.

The components are open source and built using React. You can either use them directly,
or use our fully-hosted option and embed Components in your app through iFrame or mobile
web views. Both options provide full theming customisation, and you can pick and choose
which components to use.

The smart charging app is available as a hosted option only, as Axle manages the whole customer
integration for you.

## Choosing a rendering option

|                                   | React components                         | Hosted components                          | Smart charging app                              |
| --------------------------------- | ---------------------------------------- | ------------------------------------------ | ----------------------------------------------- |
| **Customisable theming**          | ✅                                        | ✅                                          | ✅                                               |
| **Plug and play**                 | ❌ - Use in existing React website        | ❌ - You pick the components to use         | ✅ - Axle provides the whole smart-charging flow |
| **Build my own flow**             | ✅ - Use what you need in an existing app | ✅ - Embed what you need in an existing app | ❌                                               |
| **Enhance an existing React app** | ✅ - Drop in Axle React components        | ❌                                          | ❌                                               |

## Authentication

Regardless of how you choose to render, you'll need to obtain an end-user scoped component
token that can be used to authenticate API calls made from the frontend. This is a token
scoped to a specific user for use with components only, and must be created using your org scoped token.

<Note>To get your org scoped auth token, follow the [authentication guide](../../api-reference/auth/token-form). </Note>
<Danger>**Never** use your org scoped token in an untrusted environment, including all client side code.</Danger>

To generate an end user scoped token, you'll need to specify an `external_user_id` and `allowed_origin`. These are required
so Axle can reconcile your end users with the entries in our database, and to ensure that redirects or iFrame embeddings
can only happen on domains you control.

```mermaid theme={null}
sequenceDiagram
  actor user as End User
  participant be as Your Backend
  participant axle as Axle

  user->>be: Authenticates with you using<br>your existing auth flow
  be->>axle: Get component scoped token
  Note over axle: Axle creates a Site entity<br>using provided external_user_id
  axle->>be: Return end user scoped token
  be->>user: Return end user scoped token to frontend
  user<<->>axle: Frontend components talk directly to Axle using scoped token
```

You can obtain a component token by calling the `/auth/component-token/` endpoint:

```bash Request theme={null}
curl -X 'POST' \
  'https://api.axle.energy/auth/component-token' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_ORG_SCOPED_TOKEN>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'external_user_id=<YOUR_USER_ID>&allowed_origin=<YOUR_TRUSTED_ORIGIN>'
```

```json Response theme={null}
{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30" }
```

### Refreshing tokens

Component tokens are valid for **one hour**. You should regenerate component tokens before this to ensure
user flows aren't interrupted.