LLM Context

Use this page as implementation context for AI coding agents and developer assistants. It summarizes the flinkey partner integration model without replacing the API Reference or Mobile SDK documentation.

Standard integration model

The standard flinkey partner integration uses:

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

flowchart LR
    customer[End customer] --> app[Partner mobile app]
    app --> backend[Partner backend]
    backend --> api[flinkey API]
    api --> webhook[Partner webhook endpoint]
    webhook --> backend
    backend --> appContext[Mobile access context]
    appContext --> app
    app --> sdk[Tapkey Mobile SDK]
    sdk --> fBox[flinkey BLE Box]

The customer uses the partner mobile app — not the flinkey App. The partner backend is responsible for all server-side flinkey API communication. The partner mobile app handles the customer-facing access flow and local BLE communication.

System responsibilities

Partner backend

The partner backend must:

Authenticate partner customers
Decide whether a customer may access a vehicle
Store integration configuration securely
Authenticate against the flinkey API (POST /oauth2/token)
Resolve customer context (GET /customers)
Create or resolve cars
Create or resolve anonymous flinkey users
Create, update and delete assignments
Receive and process assignment webhooks
Persist flinkey IDs and partner mappings
Provide mobile access context to the partner app

The partner backend must not expose backend credentials to the mobile app.

Partner mobile app

The partner mobile app must:

Authenticate the customer against the partner backend
Request mobile access context from the partner backend
Integrate the Tapkey Mobile SDK
Integrate the WITTE Mobile Library (where Box Commands or box feedback parsing are required)
For advanced box control (double press, auto-lock, generic keyfob sequences), build custom command data per the Box Commands — Advanced protocol specification
Handle Bluetooth permissions
Perform local BLE access flow
Execute Box Commands only after valid mobile access context is available
Show clear access status to the customer
Handle user-facing error states

The partner mobile app must not call the flinkey API directly with backend credentials.

Webhook endpoint

The partner webhook endpoint must:

Receive HTTPS POST requests from flinkey
Validate the webhook secret if configured
Process events idempotently
Persist received assignment operation results
Update local assignment state
Surface failed operations to support or operations

Credential contract

Never hardcode

Never hardcode the following values in source code:

API Manager username and password
flinkey-API-Key
Backend bearer tokens
SDK Keys
Webhook secrets
GitHub Packages credentials
IdTokens, Tapkey access tokens, digital keys

Never expose to mobile app

The partner mobile app must never receive:

API Manager username or password
flinkey-API-Key
Backend bearer token
Webhook secret

The mobile app may only receive mobile-specific access context required for SDK-based access.

Never log

Do not log: passwords, API keys, bearer tokens, SDK Keys, webhook secrets, IdTokens, Tapkey access tokens, digital keys, or full mobile access context if it contains sensitive values.

Use placeholders

If a value is not available, use placeholders:

{{FLINKEY_API_BASE_URL}}
{{FLINKEY_API_MANAGER_USERNAME}}
{{FLINKEY_API_MANAGER_PASSWORD}}
{{flinkeyApiKey}}
{{FLINKEY_CUSTOMER_ID}}
{{FLINKEY_WEBHOOK_SECRET}}
{{TAPKEY_SDK_KEY}}

Do not invent realistic-looking IDs, secrets or tokens.

Environment variables

The partner backend should use environment variables or a secure secret manager.

Backend variables

FLINKEY_API_BASE_URL=https://api-uat.flinkey.de/v3
FLINKEY_API_MANAGER_USERNAME={{FLINKEY_API_MANAGER_USERNAME}}
FLINKEY_API_MANAGER_PASSWORD={{FLINKEY_API_MANAGER_PASSWORD}}
FLINKEY_API_KEY={{flinkeyApiKey}}
FLINKEY_CUSTOMER_ID={{FLINKEY_CUSTOMER_ID}}
FLINKEY_WEBHOOK_SECRET={{FLINKEY_WEBHOOK_SECRET}}

Mobile configuration

TAPKEY_SDK_KEY={{TAPKEY_SDK_KEY}}
PARTNER_BACKEND_BASE_URL={{PARTNER_BACKEND_BASE_URL}}

Mobile apps must not contain FLINKEY_API_MANAGER_PASSWORD, FLINKEY_API_KEY or any backend credentials.

Required local mappings

The partner backend should persist mappings between partner objects and flinkey objects.

Customer mapping

partner_customer_id
flinkey_user_id
environment
created_at
updated_at

Vehicle mapping

partner_vehicle_id
flinkey_customer_id
flinkey_car_id
environment
created_at
updated_at

Assignment mapping

partner_access_context_id
partner_customer_id
partner_vehicle_id
flinkey_customer_id
flinkey_user_id
flinkey_car_id
flinkey_assignment_id
assignment_status
assignment_start
assignment_end
last_webhook_received_at
last_error_message
environment
created_at
updated_at

Webhook event storage

webhook_event_id
event_type
received_at
processed_at
processing_status
checksum
flinkey_customer_id
flinkey_assignment_id
operation_succeeded
error_message
environment

Do not mix object IDs across environments (UAT vs. PROD).

End-to-end flow

sequenceDiagram
    autonumber
    participant customer as EndCustomer
    participant app as PartnerApp
    participant backend as PartnerBackend
    participant api as flinkeyAPI
    participant webhook as WebhookEndpoint
    participant sdk as TapkeySDK
    participant fBox as flinkeyBox

    customer->>app: Select vehicle access
    app->>backend: Request access
    backend->>backend: Validate permission
    backend->>api: Authenticate if needed
    backend->>api: Resolve customer context
    backend->>api: Create or resolve car
    backend->>api: Create or resolve anonymous user
    backend->>api: Create assignment
    backend->>backend: Store assignment as pending
    api-->>webhook: Assignment created result
    webhook->>backend: Persist result, update state
    app->>backend: Request mobile access context
    backend-->>app: Return mobile access context
    app->>sdk: Start local access flow
    sdk->>fBox: Authenticate locally over BLE
    fBox-->>sdk: Access result
    sdk-->>app: Access result
    app-->>customer: Show access status

Agent behavior rules

Stop when inputs are missing — Do not invent missing credentials, IDs or configuration values. Report what is missing and ask.
Prefer backend-owned decisions — The backend decides authentication, authorization, user mapping and assignment state. The mobile app does not own these decisions.
Treat assignment writes as asynchronous — Do not assume creation, update or deletion is final because the API request returned successfully. The final result comes through webhook.
Use public-safe examples — Never include real tokens, credentials, customer IDs or production IDs in documentation or generated code.

Definition of done

An implementation is only acceptable if:

Backend credentials are backend-only
Mobile app does not contain backend API credentials
Customer context is resolved correctly
Car and user mappings are persisted
Assignment state is persisted and finalized through webhooks
Webhook processing is idempotent
Mobile access context is backend-controlled
Tapkey Mobile SDK handles local access
Sensitive values are not logged
Missing values use placeholders or stop conditions
Tests cover success, failure and retry scenarios

External references

Resource	URL
Developer Documentation	`https://docs.witte.digital/flinkey-for-developer`
MCP Server (Model Context Protocol)	`https://mcp.witte.digital/flinkey-api`
OpenAPI Spec	`https://docs.witte.digital/flinkey-for-developer/openapi.json`