Skip to content
flinkeyflinkey for Developers

Implementation Recipes

Each recipe describes the responsibility, required inputs, expected output, agent rules and a pseudo flow. Use API Reference for exact endpoint contracts.

Authentication

Section titled “Authentication”

Use this recipe when implementing backend authentication against the flinkey API.

Reference: POST /oauth2/token — API Reference

Required inputs:

  • API Manager username
  • API Manager password
  • flinkey-API-Key

Expected output:

  • Bearer token
  • Token type
  • Expiration information

Agent rules:

  • Store credentials only in backend configuration
  • Never send API Manager credentials to the mobile app
  • Never log credentials or bearer tokens
  • Refresh or re-authenticate when the token expires
  • Handle authentication failure explicitly

Pseudo flow:

1. Read API Manager credentials from backend secret storage.
2. Send token request to flinkey API.
3. Receive bearer token.
4. Store token only in backend memory or secure backend token cache.
5. Use bearer token for subsequent backend API calls.
6. Refresh token when required.

Customer context

Section titled “Customer context”

Use this recipe to determine the flinkey customer context.

Reference: GET /customers — API Reference

Required inputs:

  • Bearer token
  • flinkey-API-Key

Expected output:

  • Available customer IDs
  • Customer names

Agent rules:

  • Resolve the correct customer context before vehicle operations
  • Use the correct Customer-ID header for customer-scoped operations
  • Persist the selected flinkey_customer_id
  • Do not assume one integration always has only one customer unless explicitly confirmed

Pseudo flow:

1. Authenticate backend against flinkey API.
2. Retrieve available customers.
3. Select configured or intended customer.
4. Persist flinkey_customer_id in backend configuration or mapping.
5. Use Customer-ID header for customer-scoped calls.

Car lifecycle

Section titled “Car lifecycle”

Use this recipe when mapping partner vehicles to flinkey cars.

Reference: Cars endpoints — API Reference

Required inputs:

  • Partner vehicle ID
  • Vehicle metadata
  • Bearer token, flinkey-API-Key, Customer-ID

Expected output:

  • flinkey_car_id

Agent rules:

  • Check whether a partner vehicle already has a flinkey car mapping
  • Do not create duplicate cars for the same partner vehicle
  • Persist flinkey_car_id
  • Use GET /cars/{carId} to validate existing mappings
  • Handle missing or deleted cars through reconciliation

Pseudo flow:

1. Look up partner_vehicle_id in local mapping table.
2. If flinkey_car_id exists, call Get car to validate it.
3. If no mapping exists, create or resolve the car.
4. Persist partner_vehicle_id -> flinkey_car_id.
5. Use flinkey_car_id for assignment operations.

Anonymous user lifecycle

Section titled “Anonymous user lifecycle”

Use this recipe when granting access to customers who should not sign in to the flinkey App.

Reference: Users endpoints — API Reference

Required inputs:

  • Partner customer ID
  • Bearer token, flinkey-API-Key, Customer-ID

Expected output:

  • flinkey_user_id

Agent rules:

  • Use anonymous flinkey users for standard full partner integrations
  • Persist mapping between partner customer and flinkey user
  • Do not require end customers to create flinkey App accounts by default
  • Do not create duplicate users for the same partner customer without reconciliation

Pseudo flow:

1. Authenticate customer in partner system.
2. Look up partner_customer_id in local mapping table.
3. If flinkey_user_id exists, reuse it.
4. If no mapping exists, create or resolve an anonymous flinkey user.
5. Persist partner_customer_id -> flinkey_user_id.
6. Use flinkey_user_id for assignment operations.

Assignment lifecycle

Section titled “Assignment lifecycle”

Use this recipe when granting vehicle access.

Reference: Assignments endpoints — API Reference

Required inputs:

  • flinkey_customer_id, flinkey_car_id, flinkey_user_id
  • Assignment start time
  • Assignment end time or unrestricted end
  • Bearer token, flinkey-API-Key, Customer-ID

Expected output:

  • Pending assignment operation
  • Final assignment result through webhook

Agent rules:

  • Do not treat assignment write requests as final immediately
  • Wait for the corresponding webhook result
  • Persist pending assignment state
  • Update assignment state after webhook processing
  • Use idempotency and reconciliation before retries
  • Do not create overlapping or duplicate assignments unless intended

Pseudo flow:

1. Verify partner customer is allowed to access partner vehicle.
2. Resolve flinkey_customer_id.
3. Resolve flinkey_car_id.
4. Resolve flinkey_user_id.
5. Create assignment.
6. Store local assignment state as pending.
7. Wait for assignment created result webhook.
8. If operationSucceeded = true, mark assignment active.
9. If operationSucceeded = false, mark assignment failed and store errorMessage.

Mobile access context

Section titled “Mobile access context”

Use this recipe when the partner mobile app needs to perform local vehicle access.

Reference: Mobile SDK | Android | iOS

Required inputs:

  • Authenticated partner customer
  • Partner vehicle ID
  • Active or valid assignment
  • flinkey_user_id, flinkey_car_id
  • SDK-related backend operation

Expected output:

  • Mobile access context for the partner app

Agent rules:

  • Backend validates customer access before returning mobile context
  • Mobile app does not decide assignment validity alone
  • Mobile app does not receive backend API credentials
  • Mobile app uses Tapkey Mobile SDK for local access
  • Mobile app uses WITTE Mobile Library helpers for Box Commands and box feedback parsing where required
  • Mobile app handles Bluetooth, command execution and local access errors

Pseudo flow:

1. Partner app authenticates customer against partner backend.
2. Partner app requests mobile access context for selected vehicle.
3. Partner backend verifies access permission.
4. Partner backend confirms assignment state.
5. Partner backend obtains required SDK/mobile token context.
6. Partner backend returns mobile-specific access context.
7. Partner app uses Tapkey Mobile SDK for local BLE access.

Box Commands

Section titled “Box Commands”

Use this recipe when the partner mobile app needs box-specific local BLE behavior beyond a simple access trigger.

Reference: Box Commands

Required inputs:

  • Authenticated partner customer
  • Valid mobile access context
  • Initialized Tapkey Mobile SDK
  • Relevant physical lock ID or box identifier
  • Selected Box Command type
  • WITTE Mobile Library version used by the partner app

Expected output:

  • Local command execution result
  • Optional structured box feedback

Agent rules:

  • Box Commands are local BLE commands, not REST API endpoints
  • Box Commands do not replace assignments
  • Box Commands must not bypass backend authorization
  • Execute Box Commands only after the app has valid mobile access context
  • Use WITTE Mobile Library helpers such as BoxCommandBuilder
  • For advanced use cases (double press, timed auto-lock, generic keyfob control), use custom command data built according to the Box Commands — Advanced protocol reference
  • Use the Box Command Configurator to generate and validate custom command payloads
  • Parse response data as box feedback only when the command result contains response data
  • Convert box feedback into clear app states or diagnostics
  • Do not expose raw protocol values directly to end customers

Typical command types: Unlock car + unlock box, Unlock car + lock box, Lock car + lock box, Status, Read NFC

Advanced command types: Double unlock (2 presses with pause), Double lock (deadlock activation), Unlock + auto lock after delay, Generic keyfob button sequences

Pseudo flow:

1. Partner app authenticates customer against partner backend.
2. Partner app requests mobile access context for selected vehicle.
3. Partner backend validates access permission and assignment state.
4. Partner app initializes Tapkey Mobile SDK.
5. Partner app resolves the relevant physical lock ID or box identifier.
6. Partner app builds custom command data:
   a. Standard commands: use WITTE Mobile Library BoxCommandBuilder.
   b. Advanced commands: build 16-byte custom command data per protocol spec.
7. Partner app executes the command through the local BLE command execution flow.
8. Partner app evaluates the command result.
9. If response data is available, parse BoxFeedbackV3.
10. Convert feedback into user-facing state, diagnostics or support information.

Webhook handling

Section titled “Webhook handling”

Use this recipe when implementing the partner webhook endpoint.

Reference: Webhooks

Required inputs:

  • HTTPS webhook endpoint
  • Optional webhook secret
  • Assignment mapping table
  • Webhook event storage

Expected output:

  • Persisted webhook event
  • Updated assignment state

Agent rules:

  • Validate secret header if configured
  • Parse JSON safely
  • Process events idempotently
  • Persist operation result
  • Update assignment state only after validation
  • Do not log webhook secrets
  • Surface failed assignment operations

Pseudo flow:

1. Receive webhook request.
2. Validate HTTPS and route.
3. Validate secret header if configured.
4. Validate payload structure.
5. Determine event type.
6. Persist webhook event.
7. Resolve local assignment context.
8. Update assignment state.
9. Return 200 OK or 204 No Content after successful persistence.
10. Alert or escalate failed operation results.

Prompt templates

Section titled “Prompt templates”

Use these prompts when working with AI coding agents.

Backend integration prompt

Section titled “Backend integration prompt”
You are implementing a flinkey partner backend integration.


Use the following architecture:
- Partner backend calls the flinkey API.
- Partner mobile app does not call the flinkey API with backend credentials.
- End customers use the partner app.
- Anonymous flinkey users are used for standard full partner integrations.
- Assignment write operations are asynchronous and finalized through webhooks.


Use placeholders for all credentials and IDs.


Never hardcode or log:
- API Manager credentials
- flinkey-API-Key
- bearer tokens
- SDK Keys
- webhook secrets


Implement:
1. authentication,
2. customer context resolution,
3. car mapping,
4. anonymous user mapping,
5. assignment creation,
6. webhook handling,
7. mobile access context endpoint.


Stop and ask for missing configuration instead of inventing values.

Mobile integration prompt

Section titled “Mobile integration prompt”
You are implementing a flinkey mobile integration.


Use the Tapkey Mobile SDK.


The mobile app:
- authenticates the customer against the partner backend,
- requests mobile access context from the partner backend,
- uses the Tapkey Mobile SDK for local BLE access,
- uses WITTE Mobile Library BoxCommandBuilder for standard commands,
- for advanced commands (double press, auto-lock, generic keyfob control), builds 16-byte custom command data per the protocol specification in Box Commands — Advanced,
- handles Bluetooth permissions and access errors,
- does not call the flinkey API directly with backend credentials.


Never include in the mobile app:
- API Manager credentials
- flinkey-API-Key
- backend bearer tokens
- webhook secrets


Use the backend as the source of truth for access permission.


Stop and report missing SDK setup, token context, Bluetooth permission handling or mobile access context.

Webhook implementation prompt

Section titled “Webhook implementation prompt”
You are implementing flinkey webhook handling in a partner backend.


The webhook endpoint receives assignment operation results.


Required behavior:
- expose HTTPS POST endpoint,
- validate secret header if configured,
- parse JSON safely,
- process events idempotently,
- persist webhook events,
- update local assignment state,
- store errorMessage for failed operations,
- return success only after event acceptance and persistence.


Do not log webhook secrets.


Do not treat assignment write operations as final until the corresponding webhook result has been processed.


Stop and ask for missing webhook secret, event schema or local mapping strategy instead of inventing behavior.

Test scenarios

Section titled “Test scenarios”

Use these scenarios to validate generated code.

Backend scenarios

Section titled “Backend scenarios”
  • API authentication succeeds
  • API authentication fails with invalid credentials
  • Customer context is resolved / is missing
  • Existing car mapping is valid / returns not found
  • Anonymous user mapping exists / must be created
  • Assignment creation request is accepted
  • Assignment webhook succeeds / fails
  • Webhook is received twice (idempotency)
  • Webhook secret is invalid
  • Assignment webhook arrives for unknown local assignment

Mobile scenarios

Section titled “Mobile scenarios”
  • Customer is signed in / not signed in
  • Mobile access context is returned / is missing
  • Tapkey Mobile SDK login succeeds / fails
  • Bluetooth is disabled / permission denied
  • flinkey BLE Box is found / not found
  • Local access succeeds / fails
  • Token refresh succeeds / fails

Security scenarios

Section titled “Security scenarios”
  • Logs do not contain credentials, tokens or webhook secrets
  • Mobile app bundle does not contain backend credentials
  • Git repository does not contain secrets
  • Error messages do not expose sensitive values