API Playbooks

These playbooks describe how to combine API calls, local persistence, webhook handling and error handling into stable integration flows. For the first technical walkthrough, start with the Quickstart.

Recommended implementation order

flowchart TD
    auth[Authentication] --> customer[Customer context]
    customer --> car[Car lifecycle]
    car --> user[Anonymous user lifecycle]
    user --> assignment[Assignment lifecycle]
    assignment --> webhook[Webhook handling]
    webhook --> errors[Error handling]
    errors --> hardening[Production hardening]

Customer context

All API operations run within a specific customer context. The Customer represents your organization or tenant — not the end customer or driver.

Steps:

1. Retrieve an access token (see Authentication).
2. Call GET /customers without a Customer-ID header.
3. Confirm that your intended Customer-ID is in the response.
4. Store the Customer-ID in your backend configuration.
5. Use it for all subsequent customer-scoped API calls.

Caution

Keep UAT and PROD Customer-IDs strictly separated. Accidentally using a UAT Customer-ID in PROD is a common error.

Car lifecycle

For developers, the flinkey BLE Box is abstracted behind the Car concept. Your backend works with cars, not directly with boxes.

Mapping: Partner vehicle → flinkey Car

Steps:

1. Determine the partner vehicle object.
2. Check whether a flinkey car mapping already exists locally.
3. If yes, use the stored flinkey carId.
4. If no, resolve or create the car through the API.
5. Persist the mapping between partner vehicle and flinkey car.
6. Use the flinkey carId for assignments.

Recommended local persistence:

Field	Description
partner_vehicle_id	Your internal vehicle identifier
flinkey_customer_id	Customer context
flinkey_car_id	flinkey car identifier
environment	UAT or PROD
status	Current state

Tip

Always check local mapping before creating a new car. Avoid creating duplicate cars for the same partner vehicle.

Anonymous user lifecycle

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

Mapping: Partner customer / driver → anonymous flinkey User

Steps:

1. Determine the partner customer or driver context.
2. Check whether a flinkey user mapping already exists locally.
3. If yes, use the stored flinkey userId.
4. If no, create an anonymous user through the API.
5. Persist the mapping.
6. Use the flinkey userId for assignments.

Design decision: Should one partner customer map to one anonymous flinkey user, or should each booking create a separate user?

Recommended default: One partner customer or driver maps to one anonymous flinkey user per environment.

Caution

Anonymous users cannot sign in to the flinkey App. If your customers need the flinkey App, use normal flinkey users instead.

Assignment lifecycle

An Assignment grants a user access to a car. It is the central access-control object in the integration.

Mapping: Partner booking / rental / access context → flinkey Assignment

Creating an assignment

1. Resolve the partner vehicle to a flinkey carId.
2. Resolve the partner customer/driver to a flinkey userId.
3. Validate assignment start and end time (use UTC).
4. Create the assignment through the API.
5. Store the local assignment as pending.
6. Wait for the assignment webhook.
7. Update local state based on the webhook result.

Caution

The initial API response is a request acceptance — not final success. Always process the webhook result before treating an assignment as active.

Assignment state model

stateDiagram-v2
    [*] --> Draft
    Draft --> Requested
    Requested --> PendingWebhook
    PendingWebhook --> Active: operation succeeded
    PendingWebhook --> Failed: operation failed
    Active --> UpdateRequested
    UpdateRequested --> PendingWebhook
    Active --> DeleteRequested
    DeleteRequested --> Deleted: operation succeeded
    DeleteRequested --> DeleteFailed: operation failed
    Failed --> Requested: retry after reconciliation
    Deleted --> [*]

Recommended local persistence

Field	Description
partner_access_context_id	Your booking / rental ID
flinkey_user_id	Assigned user
flinkey_car_id	Target vehicle
flinkey_assignment_id	Assignment ID (from webhook)
assignment_status	Local state (Draft → Active → Deleted)
assignment_start / assignment_end	Access time window
last_webhook_received_at	When the last webhook arrived
last_error_message	Error detail if operation failed

Error handling

Categorize errors consistently across your integration:

Category	Typical cause	Action
ConfigurationError	Missing env var or wrong environment	Fail fast, notify integration owner
AuthenticationError	Invalid API Manager credentials	Stop retrying, fix credentials
ValidationError	Invalid request payload	Fix implementation or input
NotFoundError	Missing car, user or assignment	Reconcile local mapping
ConflictError	Duplicate or inconsistent state	Reconcile before retry
RateLimitError	Too many requests	Retry with backoff
RemoteServiceError	API unavailable	Retry with backoff, monitor
WebhookValidationError	Invalid webhook secret	Reject and investigate
AsyncOperationFailed	Webhook reports failure	Mark local state failed, escalate
TimeoutError	No webhook received	Keep pending, monitor, reconcile

Logging rules

Never log: API keys, API Manager credentials, bearer tokens, webhook secrets, SDK Keys.

Safe to log: Environment, partner object IDs, flinkey object IDs, operation type, error category, correlation ID, timestamp.

Retry rules

• Retry transient network errors with exponential backoff.
• Retry token refresh once after token expiry.
• Never retry invalid credentials.
• Never blindly retry assignment creation if the first request may have succeeded.
• Reconcile state before retrying operations that create remote objects.
• Treat webhook timeout as pending — not automatically failed.

Production hardening

Before going to PROD, add:

• Monitoring and alerting
• Credential rotation process
• Strict UAT/PROD separation
• Webhook retry visibility
• Operational dashboards
• Support runbooks