> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumenaza.de/llms.txt
> Use this file to discover all available pages before exploring further.
# Lumenaza API: Quickstart
> Make your first Lumenaza API call in three steps: obtain an OAuth 2.0 token, verify access, and register your first renewable energy consumer.
This guide walks you through everything you need to make your first successful call to the Lumenaza API. By the end, you will have obtained an access token, confirmed connectivity to the test environment, and registered a consumer — all using plain HTTP requests you can run directly from your terminal.
## Prerequisites
Before you begin, make sure you have the following:
* **OAuth 2.0 client credentials** (`client_id` and `client_secret`) issued by Lumenaza for your organization. If you do not have these yet, contact your Lumenaza account manager.
* `curl` or an equivalent HTTP client (Postman, Insomnia, etc.) installed locally.
* Access to the **test environment** at `https://api.test.lumenaza.de/` — no production data is affected during this guide.
All examples below target the **test environment**. To use the production environment, replace `https://api.test.lumenaza.de/` with `https://api.lumenaza.de/` in every URL. Never run exploratory or development requests against production.
***
## Steps
The Lumenaza API uses the **OAuth 2.0 client credentials** flow. Send a `POST` request to the token endpoint with your credentials to receive a bearer token.
**Token endpoint:** `https://api.test.lumenaza.de/oauth2/token/`
```bash curl theme={null}
curl --request POST \
--url https://api.test.lumenaza.de/oauth2/token/ \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials" \
--data "client_id=YOUR_CLIENT_ID" \
--data "client_secret=YOUR_CLIENT_SECRET"
```
A successful response returns a JSON object containing your `access_token` and its lifetime in seconds:
```json theme={null}
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "read write"
}
```
Copy the value of `access_token` — you will use it as the `Bearer` token in all subsequent requests.
Access tokens expire after the number of seconds indicated by `expires_in` (typically 3 600 seconds / 1 hour). When a token expires, your requests will receive a `401 Unauthorized` response. Simply repeat this step to obtain a fresh token. Build token refresh logic into your integration from the start so that long-running processes are never interrupted.
Verify that your token works by fetching the list of consumers registered under your organization. This endpoint returns an empty list if you have not registered any consumers yet — that is expected.
**Endpoint:** `GET https://api.test.lumenaza.de/v3/consumers/`
```bash curl theme={null}
curl --request GET \
--url https://api.test.lumenaza.de/v3/consumers/ \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
A successful response looks like this:
```json theme={null}
{
"count": 0,
"next": null,
"previous": null,
"results": []
}
```
If you receive a `401 Unauthorized` error, your token may have expired or been copied incorrectly. Re-run Step 1 to obtain a new token and try again.
Always include the `Authorization: Bearer` header on every request. Omitting it or using a malformed value results in a `401` error and the request will not be processed.
Now register a consumer (electricity buyer) under your organization. Send a `POST` request to `/v3/consumers/create/` with a JSON body containing the required fields.
**Endpoint:** `POST https://api.test.lumenaza.de/v3/consumers/create/`
```bash curl theme={null}
curl --request POST \
--url https://api.test.lumenaza.de/v3/consumers/create/ \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"first_name": "Ada",
"last_name": "Lovelace",
"email": "ada.lovelace@example.com",
"salutation": "ms",
"is_business": false,
"deliv_address_street": "Musterstraße",
"deliv_address_house_number": "12",
"deliv_address_zipcode": "10115",
"deliv_address_city": "Berlin",
"annual_consumption": 3500,
"subscription_reason": "move_in",
"tariff_type": "green_standard"
}'
```
The required fields for consumer registration are:
| Field | Type | Description |
| - | - | - |
| `first_name` | string | Consumer's given name |
| `last_name` | string | Consumer's family name |
| `email` | string | Contact email address |
| `salutation` | string | Salutation code (e.g. `"mr"`, `"ms"`) |
| `is_business` | boolean | `true` for business accounts, `false` for private |
| `deliv_address_street` | string | Street name of the delivery address |
| `deliv_address_house_number` | string | House number of the delivery address |
| `deliv_address_zipcode` | string | Postal code of the delivery address |
| `deliv_address_city` | string | City of the delivery address |
| `annual_consumption` | integer | Estimated annual consumption in kWh |
| `subscription_reason` | string | Reason for joining (e.g. `"move_in"`, `"supplier_change"`) |
| `tariff_type` | string | Identifier of the tariff to assign |
A successful `201 Created` response returns the new consumer and contract identifiers:
```json theme={null}
{
"consumer_id": "CON-0001234",
"contract_id": "CTR-0009876"
}
```
Store both identifiers — you will use `consumer_id` to manage the account and `contract_id` to interact with billing and metering endpoints.
***
## Next Steps
You have authenticated, verified API access, and registered your first consumer. From here you can:
* **Explore the API Reference** to see every available endpoint, full request schemas, and error codes.
* **Learn about contract lifecycle** — how to activate, amend, and terminate contracts.
* **Submit metering data** for consumers and producers.
* **Register producers** (renewable energy plant operators) using a similar flow under `/v3/producers/`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.