Concepts

This page explains the core concepts used throughout the flinkey platform. Understanding these concepts is essential before implementing the API or Mobile SDK.

Concept overview

flowchart LR
    customer[Customer] --> car[Car]
    customer --> user[User]
    user --> assignment[Assignment]
    car --> assignment
    assignment --> digitalKey[Digital key]
    assignment --> webhook[Webhook event]
    sdkKey[SDK Key] --> app[Partner mobile app]
    apiManager[API Manager] --> backend[Partner backend]
    backend --> customer
    app --> digitalKey

Customer

A Customer represents the partner’s organizational context inside flinkey — not the end customer or driver.

Most partner API calls are executed within a specific Customer context. Cars, users, assignments and related resources all belong to a Customer.

Aspect	Detail
Typical mapping	Partner organization or tenant
Source	flinkey Portal
Environment variable	FLINKEY_CUSTOMER_ID

Tip

UAT and PROD use separate Customer-IDs. Never mix them.

API Manager

An API Manager is a technical account used by the partner backend to authenticate against the flinkey API and request OAuth access tokens.

Aspect	Detail
Typical mapping	Backend service credentials
Used for	POST /oauth2/token
Environment variables	FLINKEY_API_MANAGER_USERNAME, FLINKEY_API_MANAGER_PASSWORD

Danger

API Manager credentials must only be used in trusted backend systems — never in mobile apps, frontend applications or AI prompts.

Car

A Car represents the vehicle access context in flinkey. The flinkey BLE Box is abstracted behind this concept — you work with cars, not directly with boxes.

Aspect	Detail
Typical mapping	Partner vehicle object
Used for	Assignments, vehicle access
Key field	carId

Operational topics such as Keyless Start and steering wheel lock are covered in Operations. For Box Commands see the dedicated Box Commands guide.

User

A User represents a person or technical access identity in flinkey. There are two user models:

Model	When to use
Anonymous user (default)	Full partner integration — customer uses the partner app
Normal user	Customer is expected to sign in to the flinkey App

In the default integration, the partner system remains the source of truth for customer identity. Anonymous flinkey users are created for access purposes only.

Anonymous user

An anonymous user allows flinkey to issue and manage access permissions without making the end customer part of the flinkey App login journey.

Aspect	Detail
Typical mapping	Partner customer / driver → anonymous flinkey user ID
Key field	userId
Persist	Map flinkey userId to your partner customer or driver

Assignment

An Assignment is the central access-control object — it grants a user access to a car.

Field	Description
User	The driver receiving access
Car	The vehicle being accessed
Start time	When access begins
End time	When access ends (or unrestricted)

Typical mapping: partner booking, rental, reservation or access context → flinkey Assignment.

Caution

Assignment operations may be asynchronous. The initial API response is a request acceptance — not final success. Always process the webhook result before treating the assignment as complete.

Assignment lifecycle

stateDiagram-v2
    [*] --> Requested
    Requested --> PendingWebhook
    PendingWebhook --> Active: operation succeeded
    PendingWebhook --> Failed: operation failed
    Active --> UpdateRequested
    UpdateRequested --> PendingWebhook
    Active --> DeleteRequested
    DeleteRequested --> Deleted
    Failed --> [*]
    Deleted --> [*]

Digital key

A digital key is the digital access credential that authenticates the driver against the flinkey BLE Box at the vehicle.

• Not the physical vehicle key (the original key remains inside the BLE Box).
• Derived from the assignment’s access permission.
• Used by the Tapkey Mobile SDK for local BLE authentication.
• Supports offline vehicle access through a challenge/response mechanism — no server contact required at the moment of trigger.
• Valid for the assignment’s configured lifetime (default: 604800 seconds = 7 days).
• Renewed automatically by the SDK in the background after renewableAfter (default: half the lifetime).
• Cannot be revoked offline — revocation takes effect only after the next key synchronization.

See Offline Access for implementation details and common pitfalls.

Webhook

A Webhook is an HTTPS callback from flinkey to the partner backend, used to deliver asynchronous operation results — especially assignment results.

Event type	Triggered when
Assignment created	A new assignment has been processed
Assignment updated	An existing assignment has been modified
Assignment deleted	An assignment has been removed

Your webhook endpoint should validate the webhook secret, process events idempotently and persist state changes. See the Webhooks guide for details.

SDK Key

An SDK Key is required for partner app integrations with the Tapkey Mobile SDK. It is managed in the flinkey Portal.

Aspect	Detail
Environment variable	FLINKEY_SDK_KEY
Used by	Partner mobile app → Tapkey Mobile SDK

Use separate SDK Keys for different environments or app contexts when applicable.

Concept relationships

erDiagram
    CUSTOMER ||--o{ API_MANAGER : has
    CUSTOMER ||--o{ CAR : contains
    CUSTOMER ||--o{ USER : contains
    USER ||--o{ ASSIGNMENT : receives
    CAR ||--o{ ASSIGNMENT : grants_access_to
    ASSIGNMENT ||--o{ DIGITAL_KEY : enables
    ASSIGNMENT ||--o{ WEBHOOK_EVENT : produces
    SDK_KEY ||--o{ PARTNER_APP : configures

Key mappings

Partner concept	flinkey concept
Organization / tenant	Customer
Vehicle	Car
Customer / driver	Anonymous User
Booking / rental / access context	Assignment
Asynchronous result	Webhook event