> ## 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.
# Component token
> Authenticate on behalf of an end user by supplying their external user ID.
This endpoint is used by authenticated API clients to create a user-scoped access token for a specific end user (referenced by their external ID) in the API client's organisation. If no such end user exists, one will be created on demand.
Returns a bearer access token scoped to this end user upon success.
This token is site-scoped and valid for 24 hours, longer-lived than the standard organisation token (1 hour) as it is intended for end-user sessions.
Component tokens are site-scoped and valid for **24 hours** — longer-lived than the standard [organisation token](./token-form) (1 hour), since they're intended for end-user sessions.
## Supplying `user_email`
A user email is required to process payments through our provider, Stripe. We also send payment-failure notifications and, if enabled, two-factor authentication codes to this address.
The field upserts onto the user record, so it's safe to set on every call.
## OpenAPI
````yaml POST /auth/component-token
openapi: 3.1.0
info:
title: Axle API Docs
description: >-
For full documentation please see our official docs at docs.axle.energy
version: 1.4.6
servers:
- url: https://api-sandbox.axle.energy
security: []
tags:
- name: 1. Authentication
description: Authenticate yourself with the Axle API
- name: 2. Meters
description: Find key info about your sites
- name: 3. Sites
description: Register your sites with Axle; configure market participation
- name: 4. Assets
description: Register your assets with Axle
- name: 5. Data
description: Send asset metrics to Axle, for analysis and optimisation purposes
- name: 6. Rewards
description: >-
Determine how much your users have earned by participating with Axle;
allow balance withdrawal
- name: 7. Validation
description: Validate structured data against Axle's rules
- name: 8. Examples
description: Get example data for testing
paths:
/auth/component-token:
post:
tags:
- 1. Authentication
summary: Create Component Token
description: >-
Authenticate on behalf of an end user by supplying their external user
ID.
This endpoint is used by authenticated API clients to create a
user-scoped access token for a specific end user (referenced by their
external ID) in the API client's organisation. If no such end user
exists, one will be created on demand.
Returns a bearer access token scoped to this end user upon success.
This token is site-scoped and valid for 24 hours, longer-lived than the
standard organisation token (1 hour) as it is intended for end-user
sessions.
operationId: create_component_token_auth_component_token_post
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: >-
#/components/schemas/Body_create_component_token_auth_component_token_post
required: true
responses:
'200':
description: Successfully authenticated with a user-scoped access token
content:
application/json:
schema:
$ref: '#/components/schemas/ComponentToken'
'404':
description: Error trying to find organisation
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'500':
description: Server error when trying to find or create the user
security:
- OAuth2PasswordBearer: []
components:
schemas:
Body_create_component_token_auth_component_token_post:
properties:
external_user_id:
type: string
title: External User Id
allowed_origin:
type: string
title: Allowed Origin
user_email:
type: string
title: User Email
description: >-
The email of the user, to be added for new users or upserted for
existing users.
gave_boundary_meter_consent_at:
type: string
format: date-time
title: Gave Boundary Meter Consent At
description: >-
Timezone-aware ISO 8601 timestamp (e.g. '2026-01-01T12:34:56Z')
indicating when the household gave consent for Axle to access
readings from their boundary meter, if consent was given.
Unless explicitly exempted, this must be provided on the first call
to this endpoint (per `external_user_id`). It can optionally be
included in later calls for the same `external_user_id`; the value
submitted most recently will be kept on record.
type: object
required:
- external_user_id
- allowed_origin
title: Body_create_component_token_auth_component_token_post
ComponentToken:
properties:
id:
type: string
format: uuid
title: Id
access_token:
type: string
title: Access Token
token_type:
type: string
title: Token Type
type: object
required:
- id
- access_token
- token_type
title: ComponentToken
description: >-
Organisation scoped token. Includes internal user ID so clients can make
futher
API requests regarding this user if needed.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
OAuth2PasswordBearer:
type: oauth2
flows:
password:
scopes: {}
tokenUrl: auth/token-form
````