Skip to content
flinkeyflinkey for Developers

Integration Quickstart

This quickstart walks you through the first complete integration flow on UAT. After completing it, your backend will be able to authenticate, manage cars and users, create assignments and process webhooks.

Goal

Section titled “Goal”

After completing this quickstart you will have validated:

  1. OAuth token retrieval
  2. Customer context resolution
  3. Car creation or resolution
  4. Anonymous user creation
  5. Assignment creation
  6. Webhook reception and processing

The quickstart is successful when an assignment can be created and the corresponding webhook result is processed by your backend.

Before you start

Section titled “Before you start”

Make sure you have completed the Portal & Credentials setup and have the following ready:

  • Access to the flinkey Portal (UAT)
  • Developer feature enabled for UAT
  • Customer-ID and flinkey-API-Key
  • API Manager credentials
  • Webhook endpoint (HTTPS)
  • Webhook secret (if configured)

Quickstart sequence

Section titled “Quickstart sequence”

The integration follows this flow:

sequenceDiagram
    autonumber
    participant Backend as Partner backend
    participant API as flinkey API
    participant Webhook as Partner webhook

    Backend->>API: POST /oauth2/token
    API-->>Backend: Access token

    Backend->>API: GET /customers
    API-->>Backend: Customer-ID confirmed

    Backend->>API: PUT /cars (create or resolve)
    API-->>Backend: Car ID

    Backend->>API: PUT /users (create anonymous user)
    API-->>Backend: User ID

    Backend->>API: PUT /assignments
    API-->>Backend: Request accepted

    API-->>Webhook: Assignment result
    Webhook-->>Backend: Persist assignment state

  1. Authenticate

    Call POST /oauth2/token with your API Manager credentials and flinkey-API-Key to receive an access token. Send it as Authorization: Bearer <access_token> on all subsequent requests.

    • Read all credentials from environment variables.
    • Cache the access token and refresh when needed.
    • Never log credentials or bearer tokens.

  2. Resolve customer context

    Call GET /customers (without a Customer-ID header) to confirm your Customer-ID belongs to the authenticated API Manager. Store the Customer-ID in your backend configuration.

  3. Create or resolve a car

    Use an existing UAT car or create a test car. Persist the flinkey carId and map it to your partner vehicle object.

    The flinkey BLE Box is abstracted behind the Car concept — you do not need to interact with it directly.

  4. Create an anonymous user

    In a full partner integration, the partner system remains the source of truth for customer identity. Create an anonymous flinkey user for access purposes and map the flinkey userId to your partner customer.

  5. Create an assignment

    An assignment grants a user access to a car for a defined time period. Create an assignment for the selected userId and carId.

    Treat the initial API response as request acceptance, not as final success. Wait for the webhook to confirm the result.

  6. Receive the assignment webhook

    Your webhook endpoint receives the assignment result. Validate the webhook secret, parse the event, update the local assignment state and persist the result.

    Store at minimum: assignment ID, car ID, user ID, operation result and received timestamp.

  7. Validate the end-to-end flow

    The quickstart is complete when the full flow works on UAT: authenticate → resolve customer → resolve car → create user → create assignment → receive webhook → persist state.

Minimum persistence model

Section titled “Minimum persistence model”

Your backend should persist at least these mappings:

Partner concept flinkey mapping
Customer / driver flinkey user ID
Vehicle flinkey car ID
Booking / rental / access context flinkey assignment ID + status + webhook result

A simple table model:

flinkey_access_mappings
├── partner_customer_id
├── partner_vehicle_id
├── partner_access_context_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

Error handling

Section titled “Error handling”

Your quickstart implementation should handle at least:

  • Missing environment variables
  • Authentication failure
  • Invalid or missing Customer-ID
  • Car not found
  • User creation failure
  • Assignment request failure
  • Webhook secret validation failure
  • Assignment webhook reporting a failed operation
  • Duplicate webhook events
  • Timeout while waiting for webhook

Quickstart checklist

Section titled “Quickstart checklist”
  • Backend configuration loaded from environment variables
  • Required environment variables validated at startup
  • OAuth token retrieval works
  • Customer context resolved or validated
  • A car can be resolved or created
  • An anonymous user can be created or resolved
  • An assignment can be created
  • Assignment webhook is received
  • Webhook secret is validated (if configured)
  • Assignment state is persisted
  • Partner object mappings are persisted
  • Logs do not expose credentials or bearer tokens

Next steps

Section titled “Next steps”
  • Understand the core Concepts behind the integration
  • Follow the Authentication guide for token management details
  • Explore the API Playbooks for car, user and assignment lifecycle flows
  • Set up reliable Webhook processing