# flinkey Integration Context for LLMs

This file provides the complete flinkey integration context as a single text file for AI agents and LLM-based systems.

Document version: 0.20
Last updated: 2026-07-26

---

## What is flinkey?

flinkey digitizes vehicle access by combining backend permissions, mobile access, local BLE authentication and a physical flinkey BLE Box installed in the vehicle. The partner integrates with the flinkey API to grant digital vehicle access to their customers.

---

## Integration model

Components:
- Partner backend: server-side API communication
- Partner mobile app: customer-facing access flow
- flinkey API v3: backend operations (REST, OAuth2)
- Tapkey Mobile SDK: local BLE access (Android/iOS)
- WITTE Mobile Library: Box Commands, box feedback parsing
- flinkey BLE Box: physical vehicle access device
- Partner webhook endpoint: receives asynchronous assignment results

Flow: Customer -> Partner App -> Partner Backend -> flinkey API -> Webhook -> Backend -> Mobile Access Context -> App -> Tapkey SDK -> BLE Box

---

## Environments

| Parameter | UAT | PROD |
|---|---|---|
| API Base URL | https://api-uat.flinkey.de/v3 | https://api.flinkey.de/v3 |
| Portal | https://portal-uat.flinkey.com | https://portal.flinkey.com |

Every integration starts on UAT. PROD access is granted after validation.
All credentials (Customer-ID, API-Key, API Manager, Webhook, SDK Key) are environment-specific.

---

## Core concepts

- Customer: top-level container, resolved via GET /customers
- Car: represents a vehicle with a flinkey BLE Box, created via PUT /cars
- User: access identity, typically anonymous for partner integrations, created via PUT /users
- Assignment: grants a user access to a car for a time range, created via PUT /assignments
- Webhook: HTTPS callback delivering asynchronous assignment results
- Digital key: access credential for local BLE authentication (derived from assignment)

---

## Authentication

1. POST /oauth2/token with API Manager username, password and flinkey-API-Key
2. Receive bearer token
3. Use bearer token + flinkey-API-Key for all subsequent requests
4. Add Customer-ID header for customer-scoped operations

---

## Assignment lifecycle

1. Create assignment (PUT /assignments) -> request accepted
2. Webhook delivers result (operationSucceeded: true/false)
3. Update local state based on webhook
4. Update assignment (PATCH /assignments/{id}) -> webhook result
5. Delete assignment (DELETE /assignments/{id}) -> webhook result

Assignment writes are ASYNCHRONOUS. Never treat the API response as the final result.

---

## Webhook processing

- Receive HTTPS POST from flinkey
- Validate webhook secret header if configured
- Parse JSON payload (checksum, assignmentId, customerId, operationSucceeded, errorMessage)
- Process idempotently (handle duplicate deliveries)
- Persist event and update assignment state
- Return 200 OK or 204 No Content

---

## Mobile SDK flow

1. Partner backend provides mobile access context (IdToken via POST /appsdk/idtoken)
2. Mobile app performs Tapkey SDK token exchange (AppAuth)
3. SDK resolves physical lock ID
4. SDK authenticates locally over BLE
5. Vehicle access is granted or denied

Platforms: Android (Tapkey Mobile SDK + WITTE Mobile Library for Android), iOS (Tapkey Mobile SDK + WITTE Mobile Library for Objective-C)

---

## Box Commands

Box Commands extend the standard BLE trigger with custom behavior:
- Unlock car + unlock box
- Unlock car + lock box
- Lock car + lock box
- Status query
- Read NFC tag UIDs

Box Commands are LOCAL BLE commands, not REST API endpoints. They require valid mobile access context and an initialized Tapkey Mobile SDK.

---

## Credential rules

NEVER hardcode: API Manager credentials, flinkey-API-Key, bearer tokens, SDK Keys, webhook secrets, IdTokens, Tapkey access tokens, digital keys

NEVER expose to mobile app: API Manager credentials, flinkey-API-Key, bearer tokens, webhook secrets

NEVER log: any of the above

Use environment variables or secure secret managers. Use placeholders when real values are not available.

---

## Required backend mappings

Customer mapping: partner_customer_id -> flinkey_user_id (per environment)
Vehicle mapping: partner_vehicle_id -> flinkey_car_id (per environment)
Assignment mapping: partner_access_context_id -> flinkey_assignment_id + status + webhook state
Webhook events: event_id, type, checksum, operation result, timestamps

---

## API operations summary

Authentication: POST /oauth2/token
Customers: GET /customers
Cars: GET /cars, PUT /cars, GET /cars/{carId}, PATCH /cars/{carId}, DELETE /cars/{carId}
Users: GET /users, PUT /users, GET /users/{userId}
Assignments: PUT /assignments, GET /assignments/{assignmentId}, PATCH /assignments/{assignmentId}, DELETE /assignments/{assignmentId}, GET /cars/{carId}/assignments, GET /users/{userId}/assignments
App SDK: POST /appsdk/idtoken, GET /appsdk/config
Events: GET /events
Webhooks: Callback to partner endpoint (not an API operation)
Groups: GET/PUT/DELETE for cars, users, services, products in groups
Products: GET /products, GET /products/{productId}
Services: GET /services, GET /services/{serviceId}
Installations: PUT /installations, DELETE /installations
Contracts: GET /contracts
Keyfob: GET /keyfob

Full OpenAPI 3.1 specification: /openapi.json

---

## Contact

Developer support: developers@flinkey.com
UAT Portal: https://portal-uat.flinkey.com
PROD Portal: https://portal.flinkey.com