{ "openapi": "3.1.2", "info": { "title": "flinkey API v3", "version": "0.20", "description": "Interactive API reference for the flinkey API v3.\n\nDocument version: **0.20** \nLast updated: **2026-07-23**\n\n**Important:** Every integration starts on the UAT environment. Access to the production environment is granted only after successful validation by the flinkey team.\n\nFor questions or support, contact [developers@flinkey.com](mailto:developers@flinkey.com).\n\n[Download OpenAPI specification](/openapi.json)" }, "servers": [ { "url": "https://api-uat.flinkey.de/v3", "description": "UAT — start all integrations here (Portal: https://portal-uat.flinkey.com)" }, { "url": "https://api.flinkey.de/v3", "description": "PROD — available after validation (Portal: https://portal.flinkey.com)" } ], "tags": [ { "name": "App SDK" }, { "name": "Assignments" }, { "name": "Authentication" }, { "name": "Cars" }, { "name": "Contracts" }, { "name": "Customers" }, { "name": "Events" }, { "name": "Grouping" }, { "name": "Installations" }, { "name": "Keyfob" }, { "name": "Products" }, { "name": "Services" }, { "name": "Users" }, { "name": "Webhooks" } ], "paths": { "/groups/{groupId}/cars": { "put": { "tags": [ "Grouping" ], "summary": "Assign car to group", "description": "### Purpose\n\nAssign a car to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a car must be added to an existing group.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to assign a car to a group.\n\nTypical situations:\n\n- adding a car to an operational group,\n- preparing group-based vehicle administration,\n- grouping vehicles for support workflows,\n- grouping vehicles for setup or reconciliation workflows,\n- correcting group membership after reconciliation,\n- maintaining group-based operational views.\n\nBefore assigning a car to a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `carId`,\n- whether the group exists,\n- whether the car exists,\n- whether the car is already assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty response body.\n- A subsequent `GET /groups/{groupId}/cars` returned the assigned car.\n- After removal, the same GET returned an empty array.\n\n### Async behavior\n\nSynchronous.\n\nThe group assignment result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and car identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.assignCarToGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Car was assigned to the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group or car was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping and local carId mapping" }, "409": { "description": "The car is already assigned to the group\n\nRecommended handling: Treat as already assigned if this matches the intended state, or reconcile local group-car mapping" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carId": { "type": "number", "description": "Database ID of the car to assign to the group", "example": 12345 } }, "required": [ "carId" ] }, "example": { "carId": 12345 } } } } }, "get": { "tags": [ "Grouping" ], "summary": "Get cars of group", "description": "### Purpose\n\nRetrieve cars assigned to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational lookup, reconciliation and support workflows where grouped cars must be retrieved.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve cars assigned to a specific group.\n\nTypical situations:\n\n- listing cars of a group,\n- validating group membership for cars,\n- supporting grouping-based administration workflows,\n- reconciling grouped car records with partner or support records,\n- preparing operational workflows for a subset of cars,\n- checking whether a car is assigned to the intended group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Async behavior\n\nSynchronous.\n\nThe cars assigned to the group are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and car identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.getCarsOfGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Cars of the group were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Car database ID" }, "name": { "type": "string", "description": "Car name" }, "description": { "type": [ "string", "null" ], "description": "Car description" }, "vin": { "type": [ "string", "null" ], "description": "Vehicle identification number" }, "licensePlate": { "type": [ "string", "null" ], "description": "Vehicle license plate" }, "brand": { "type": [ "string", "null" ], "description": "Vehicle brand" }, "model": { "type": [ "string", "null" ], "description": "Vehicle model" } } } }, "example": [ { "id": 12345, "name": "VW Golf Fleet-01", "description": "White VW Golf, 2024", "vin": "WVWZZZ1KZXW000001", "licensePlate": "B-FL 1234", "brand": "Volkswagen", "model": "Golf" } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/groups/{groupId}/products": { "put": { "tags": [ "Grouping" ], "summary": "Assign product to group", "description": "### Purpose\n\nAssign a product to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a product must be added to an existing group.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to assign a product to a group.\n\nTypical situations:\n\n- adding a product to an operational group,\n- preparing group-based product administration,\n- grouping products for support workflows,\n- grouping products for setup or reconciliation workflows,\n- correcting group membership after reconciliation,\n- maintaining group-based operational views,\n- grouping hardware products for operational reporting or support.\n\nBefore assigning a product to a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `productId`,\n- whether the group exists,\n- whether the product exists,\n- whether the product is already assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned the assigned product; after removal it returned an empty array.\n\n### Async behavior\n\nSynchronous.\n\nThe group assignment result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and product identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.assignProductToGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Product was assigned to the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group or product was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping and local productId mapping" }, "409": { "description": "The product is already assigned to the group\n\nRecommended handling: Treat as already assigned if this matches the intended state, or reconcile local group-product mapping" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "number", "description": "Database ID of the product to assign to the group", "example": 67890 } }, "required": [ "productId" ] }, "example": { "productId": 67890 } } } } }, "get": { "tags": [ "Grouping" ], "summary": "Get products of group", "description": "### Purpose\n\nRetrieve products assigned to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational lookup, reconciliation and support workflows where grouped products must be retrieved.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve products assigned to a specific group.\n\nTypical situations:\n\n- listing products of a group,\n- validating group membership for products,\n- supporting grouping-based administration workflows,\n- reconciling grouped product records with partner or support records,\n- preparing operational workflows for a subset of products,\n- checking whether a product is assigned to the intended group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Validation notes\n\n- PROD returned `200 OK` with a direct JSON array and no OData wrapper.\n- The collection was observed both empty and with one assigned product.\n- Assignment and subsequent removal were confirmed through control GET requests.\n- `$filter`, `$orderby`, `$top` and `$skip` were accepted as documented above.\n\n### Async behavior\n\nSynchronous.\n\nThe products assigned to the group are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and product identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.getProductsOfGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Products of the group were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Product database ID" }, "uniqueId": { "type": "string", "description": "Unique product identifier" }, "serialNumber": { "type": "string", "description": "Product serial number" }, "sapNumber": { "type": "string", "description": "SAP number" }, "dongleTerminationTimeStamp": { "type": [ "string", "null" ], "description": "Functionally obsolete legacy field from the former virtual telematics-dongle connection; do not use for integration logic" }, "type": { "type": "string", "description": "Product type, for example flinkey Box or flinkey IQ" }, "carId": { "type": [ "number", "null" ], "description": "Car currently linked to the product; returned by PROD although omitted from the public response schema" } } } }, "example": [ { "id": 67890, "uniqueId": "PU-2024-00001", "serialNumber": "SN-100200300", "sapNumber": "SAP-400500", "dongleTerminationTimeStamp": null, "type": "flinkey Box", "carId": 12345 } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/groups/{groupId}/services": { "put": { "tags": [ "Grouping" ], "summary": "Assign service to group", "description": "### Purpose\n\nAssign a service to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a service must be added to an existing group.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to assign a service to a group.\n\nTypical situations:\n\n- adding a service to an operational group,\n- preparing group-based service administration,\n- grouping services for support workflows,\n- grouping services for setup or reconciliation workflows,\n- correcting group membership after reconciliation,\n- maintaining group-based operational views.\n\nBefore assigning a service to a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `serviceId`,\n- whether the group exists,\n- whether the service exists,\n- whether the service is already assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned the assigned service; after removal it returned an empty array.\n\n### Async behavior\n\nSynchronous.\n\nThe group assignment result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and service identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or service IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.assignServiceToGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Service was assigned to the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group or service was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping and local serviceId mapping" }, "409": { "description": "The service is already assigned to the group\n\nRecommended handling: Treat as already assigned if this matches the intended state, or reconcile local group-service mapping" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceId": { "type": "number", "description": "Database ID of the service to assign to the group", "example": 11111 } }, "required": [ "serviceId" ] }, "example": { "serviceId": 11111 } } } } }, "get": { "tags": [ "Grouping" ], "summary": "Get services of group", "description": "### Purpose\n\nRetrieve services assigned to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational lookup, reconciliation and support workflows where grouped services must be retrieved.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve services assigned to a specific group.\n\nTypical situations:\n\n- listing services of a group,\n- validating group membership for services,\n- supporting grouping-based administration workflows,\n- reconciling grouped service records with partner or support records,\n- preparing operational workflows for a subset of services,\n- checking whether a service is assigned to the intended group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Validation notes\n\n- PROD returned `200 OK` with a direct JSON array and no OData wrapper.\n- The collection was observed both empty and with one assigned active service.\n- Assignment and subsequent removal were confirmed through control GET requests.\n- `$filter`, `$orderby`, `$top` and `$skip` were accepted as documented above.\n\n### Async behavior\n\nSynchronous.\n\nThe services assigned to the group are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and service identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or service IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.getServicesOfGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Services of the group were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Service database ID" }, "name": { "type": [ "string", "null" ], "description": "Service name" }, "productId": { "type": [ "number", "null" ], "description": "Product linked to the service; returned by PROD although omitted from the public response schema" }, "isTerminated": { "type": "boolean", "description": "Indicates whether the service is terminated" }, "terminationDate": { "type": [ "string", "null" ], "description": "Service termination date in date-time format, if available" }, "terminationCause": { "type": [ "string", "null" ], "description": "Termination cause, if available" } } } }, "example": [ { "id": 11111, "name": "flinkey Access", "isTerminated": false, "terminationDate": null, "terminationCause": null } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/users/assignments/customers": { "put": { "tags": [ "Users" ], "summary": "Assign user to customer", "description": "### Purpose\n\nAssign an existing user to the selected customer context.\n\nA user represents the access identity that can receive assignments for cars.\n\nThis operation links an existing user to the customer identified by the `Customer-ID` header.\n\nFor standard full partner integrations, the partner backend usually creates or resolves anonymous flinkey users directly in the intended customer context.\n\nUse this operation when an existing user must be assigned to an additional customer context.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to assign an existing flinkey user to the selected customer.\n\nTypical situations:\n\n- assigning an existing user to another customer context,\n- resolving a user that already exists but is not yet assigned to the selected customer,\n- recovering from a `409 CONFLICT` during user creation,\n- reconciling user records between partner systems and flinkey,\n- preparing an existing user for assignment creation in the selected customer context.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nDo not assign users to customer contexts without a clear business reason.\n\nDo not use this operation as a replacement for proper user lifecycle handling.\n\n### Validation notes\n\nPROD validation result:\n\n- `PUT /users/assignments/customers` with a numeric `userId` returned `204 No Content` when the existing user was not assigned to the selected customer.\n- The user was visible again through the customer-scoped user endpoints after the successful assignment.\n- Repeating the operation for a user already assigned to the customer returned `409 Conflict` with the message `Could not assign user to customer because the user is already assigned to the customer.`\n- The positive and conflict paths were validated with `userId`. The alternative `emailAddress` request form was not separately validated.\n\n### Async behavior\n\nSynchronous.\n\nThe assignment to the customer is completed directly by the API operation.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUser identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "users.assignUserToCustomer", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User was assigned to the customer successfully" }, "400": { "description": "Invalid e-mail address and userId given, or no valid identifier was provided\n\nRecommended handling: Provide either a valid emailAddress or a valid userId" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or user was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and user identifier" }, "409": { "description": "User is already assigned to the customer\n\nRecommended handling: Treat as already assigned after reconciliation" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Useful", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailAddress": { "type": [ "string", "null" ], "description": "E-mail address of the user to assign", "example": "user@example.com" }, "userId": { "type": [ "number", "null" ], "description": "Database ID of the user to assign", "example": 54321 } } }, "example": { "emailAddress": "user@example.com", "userId": 54321 } } } } }, "delete": { "tags": [ "Users" ], "summary": "Unassign user from customer", "description": "### Purpose\n\nRemove an existing user assignment from the selected customer context.\n\nA user represents the access identity that can receive assignments for cars.\n\nThis operation removes the link between an existing user and the customer identified by the `Customer-ID` header.\n\nUse this operation only when the user should no longer belong to the selected customer context.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to remove a user from the selected customer context.\n\nTypical situations:\n\n- a user should no longer be available in the selected customer context,\n- a customer-user assignment was created incorrectly,\n- a user mapping is being retired,\n- a user was assigned to the wrong customer context,\n- user/customer access data is being reconciled.\n\nBefore unassigning a user from a customer, check whether the user is still referenced by active partner processes or assignments.\n\nDo not unassign a user only because the user currently has no active assignment.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nAfter successful unassignment, update the local mapping state.\n\n### Validation notes\n\nPROD validation result:\n\n- `DELETE /users/assignments/customers` with a numeric `userId` returned `204 No Content`.\n- The user was no longer visible in the selected customer context after the operation.\n- Removal of the user-customer assignment was additionally confirmed in the application portal.\n- The same existing user was subsequently assigned to the customer again successfully.\n- The validated request used `userId`. The alternative `emailAddress` request form was not separately validated.\n\n### Async behavior\n\nSynchronous.\n\nThe unassignment from the customer is completed directly by the API operation.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUser identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "users.unassignUserFromCustomer", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "User was unassigned from the customer successfully" }, "400": { "description": "Invalid e-mail address and userId given, or no valid identifier was provided\n\nRecommended handling: Provide either a valid emailAddress or a valid userId" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, user or user-customer assignment was not found\n\nRecommended handling: Check credentials, Customer-ID, user identifier and whether the assignment exists" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Useful", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailAddress": { "type": [ "string", "null" ], "description": "E-mail address of the user to unassign", "example": "user@example.com" }, "userId": { "type": [ "number", "null" ], "description": "Database ID of the user to unassign", "example": 54321 } } }, "example": { "emailAddress": "user@example.com", "userId": 54321 } } } } } }, "/groups/{groupId}/users": { "put": { "tags": [ "Grouping" ], "summary": "Assign user to group", "description": "### Purpose\n\nAssign a user to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a user must be added to an existing group.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to assign a user to a group.\n\nTypical situations:\n\n- adding a user to an operational group,\n- preparing group-based user administration,\n- grouping users for support workflows,\n- grouping users for setup or reconciliation workflows,\n- correcting group membership after reconciliation,\n- maintaining group-based operational views.\n\nBefore assigning a user to a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `userId`,\n- whether the group exists,\n- whether the user exists,\n- whether the user is already assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned the assigned user; after removal it returned an empty array.\n\n### Async behavior\n\nSynchronous.\n\nThe group assignment result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and user identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.assignUserToGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "User was assigned to the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group or user was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping and local userId mapping" }, "409": { "description": "The user is already assigned to the group\n\nRecommended handling: Treat as already assigned if this matches the intended state, or reconcile local group-user mapping" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "number", "description": "Database ID of the user to assign to the group", "example": 54321 } }, "required": [ "userId" ] }, "example": { "userId": 54321 } } } } }, "get": { "tags": [ "Grouping" ], "summary": "Get users of group", "description": "### Purpose\n\nRetrieve users assigned to one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational lookup, reconciliation and support workflows where grouped users must be retrieved.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve users assigned to a specific group.\n\nTypical situations:\n\n- listing users of a group,\n- validating group membership for users,\n- supporting grouping-based administration workflows,\n- reconciling grouped user records with partner or support records,\n- preparing operational workflows for a subset of users,\n- checking whether a user is assigned to the intended group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Validation notes\n\n- PROD returned `200 OK` with a direct JSON array and no OData wrapper.\n- The collection was observed both empty and with one assigned user.\n- Assignment and subsequent removal were confirmed through control GET requests.\n- `$filter`, `$orderby`, `$top` and `$skip` were accepted as documented above.\n- All personal data in this document remains represented by placeholders.\n\n### Async behavior\n\nSynchronous.\n\nThe users assigned to the group are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and user identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.getUsersOfGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Users of the group were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "User database ID" }, "emailAddress": { "type": "string", "description": "User email address" }, "userData": { "type": "object", "description": "User data object" }, "userData.firstName": { "type": [ "string", "null" ], "description": "User first name" }, "userData.lastName": { "type": [ "string", "null" ], "description": "User last name" } } } }, "example": [ { "id": 54321, "emailAddress": "user@example.com", "userData": { "firstName": "Max", "lastName": "Mustermann" } } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/webhooks/assignmentCreatedResult": { "post": { "tags": [ "Webhooks" ], "summary": "Assignment created result", "description": "### Purpose\n\nReceive the asynchronous result of an assignment creation request.\n\nThis webhook is sent by flinkey after an assignment creation operation has been processed.\n\nAssignment creation is asynchronous.\n\nThe initial API response confirms that the create request was accepted.\n\nThis webhook provides the final operation result.\n\n### When to use this operation\n\nUse this webhook when the partner backend needs to finalize local assignment state after creating an assignment.\n\nTypical situations:\n\n- confirming that an assignment was created successfully,\n- storing the final `assignmentId`,\n- marking a local assignment as active,\n- marking a local assignment creation as failed,\n- storing `errorMessage` for troubleshooting,\n- enabling mobile access context after successful assignment creation,\n- reconciling pending assignment creation requests.\n\nDo not mark an assignment as active before this webhook has been processed.\n\nDo not provide mobile access context based only on the initial assignment creation API response if the partner flow requires confirmed assignment state.\n\n### Validation notes\n\nPROD validation result:\n\n- The configured create-result endpoint received an HTTP `POST` after `PUT /assignments` returned `204 No Content`.\n- The incoming request used `Content-Type: application/json; charset=utf-8`.\n- The successful payload contained numeric customer, assignment, car and user IDs.\n- `checksum` was present, `operationSucceeded` was `true` and `errorMessage` was `null`.\n- `lifetime` and `renewableAfter` were `null` in the validated payload.\n- The unrestricted assignment end was represented as an empty string in the webhook payload, while assignment read endpoints may return `null`.\n- No secret was configured for the create-result endpoint during this validation; secret transmission was validated separately with the assignment-updated webhook.\n\n### Async behavior\n\nThis webhook is the asynchronous result of `Create assignment`.\n\nThe partner backend should use this webhook to finalize local assignment state.\n\nThe initial assignment creation API response is not the final result.\n\n### Webhook result\n\nYes.\n\nThis entry describes the assignment created result webhook.\n\nUse `operationSucceeded` to decide the final local state.\n\n### Security notes\n\nNever log:\n\n- webhook secret,\n- full request headers,\n- backend bearer tokens,\n- API keys,\n- SDK Keys,\n- digital keys.\n\nValidate the `secret` header if a webhook secret is configured.\n\nDo not paste real webhook payloads containing sensitive identifiers into documentation, screenshots, tickets or AI prompts.\n\nUse placeholders in documentation and examples.\n\nThe `checksum` is not a replacement for webhook secret validation.\n\n### Endpoint ownership\n\nThe receiving endpoint is configured and operated by the integration partner.", "operationId": "webhooks.assignmentCreatedResult", "parameters": [ { "name": "secret", "in": "header", "required": false, "description": "Optional webhook secret configured in the flinkey Portal", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event was accepted and processed successfully" }, "204": { "description": "Webhook event was accepted and processed successfully without response body" }, "400": { "description": "Webhook payload is invalid or cannot be parsed\n\nRecommended handling: Reject the event and log sanitized diagnostics" }, "401": { "description": "Webhook secret is missing or invalid\n\nRecommended handling: Reject the event and do not process the payload" }, "403": { "description": "Webhook secret is invalid or request is not allowed\n\nRecommended handling: Reject the event and do not process the payload" }, "500": { "description": "Partner backend could not process the event\n\nRecommended handling: Retry or escalate according to partner webhook handling policy" } }, "security": [], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checksum": { "type": "string", "description": "Hash value generated from the payload of the initial request", "example": "abc123def456" }, "assignmentId": { "type": [ "number", "null" ], "description": "Assignment database ID, or null if creation failed", "example": 77001 }, "carId": { "type": "number", "description": "Car database ID the assignment is issued for", "example": 12345 }, "userId": { "type": "number", "description": "User database ID the assignment is issued for", "example": 54321 }, "start": { "type": "string", "description": "Assignment start time in date-time format", "example": "2026-01-31T10:00:00Z" }, "end": { "type": "string", "description": "Assignment end time; an unrestricted assignment was returned as an empty string in the validated webhook", "example": "" }, "customerId": { "type": "number", "description": "Customer database ID", "example": 99001 }, "operationSucceeded": { "type": "boolean", "description": "Indicates whether assignment creation succeeded", "example": true }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message if the operation failed", "example": null }, "lifetime": { "type": [ "number", "null" ], "description": "Assignment lifetime in seconds", "example": null }, "renewableAfter": { "type": [ "number", "null" ], "description": "Renewal timing in seconds", "example": null } }, "required": [ "checksum", "assignmentId", "carId", "userId", "start", "end", "customerId", "operationSucceeded", "errorMessage" ] }, "example": { "checksum": "abc123def456", "assignmentId": 77001, "carId": 12345, "userId": 54321, "start": "2026-01-31T10:00:00Z", "end": "", "customerId": 99001, "operationSucceeded": true, "errorMessage": null, "lifetime": null, "renewableAfter": null } } } } } }, "/webhooks/assignmentDeletedResult": { "post": { "tags": [ "Webhooks" ], "summary": "Assignment deleted result", "description": "### Purpose\n\nReceive the asynchronous result of an assignment deletion request.\n\nThis webhook is sent by flinkey after an assignment deletion operation has been processed.\n\nAssignment deletion is asynchronous.\n\nThe initial API response confirms that the deletion request was accepted.\n\nThis webhook provides the final operation result.\n\n### When to use this operation\n\nUse this webhook when the partner backend needs to finalize local assignment state after deleting an assignment.\n\nTypical situations:\n\n- confirming that an assignment deletion was processed successfully,\n- marking a local assignment as deleted,\n- marking a local assignment deletion as failed,\n- storing `errorMessage` for troubleshooting,\n- reconciling pending assignment deletion requests,\n- deciding whether access should still be shown as available in the partner system,\n- removing or disabling mobile access context after successful assignment deletion.\n\nDo not mark an assignment as deleted before this webhook has been processed.\n\nDo not rely only on the initial assignment deletion API response for final assignment state.\n\n### Validation notes\n\nPROD validation result:\n\n- The configured delete-result endpoint received an HTTP `POST` after the assignment delete API returned `204 No Content`.\n- The incoming request used `Content-Type: application/json; charset=utf-8`.\n- The successful payload contained `checksum`, numeric `assignmentId`, numeric `customerId`, `operationSucceeded: true` and `errorMessage: null`.\n- No secret was configured for the delete-result endpoint during this validation; each webhook endpoint has its own secret configuration field in the portal.\n\n### Async behavior\n\nThis webhook is the asynchronous result of `Delete assignment`.\n\nThe partner backend should use this webhook to finalize local assignment deletion state.\n\nThe initial assignment deletion API response is not the final result.\n\n### Webhook result\n\nYes.\n\nThis entry describes the assignment deleted result webhook.\n\nUse `operationSucceeded` to decide the final local deletion state.\n\n### Security notes\n\nNever log:\n\n- webhook secret,\n- full request headers,\n- backend bearer tokens,\n- API keys,\n- SDK Keys,\n- digital keys.\n\nValidate the `secret` header if a webhook secret is configured.\n\nDo not paste real webhook payloads containing sensitive identifiers into documentation, screenshots, tickets or AI prompts.\n\nUse placeholders in documentation and examples.\n\nThe `checksum` is not a replacement for webhook secret validation.\n\n### Endpoint ownership\n\nThe receiving endpoint is configured and operated by the integration partner.", "operationId": "webhooks.assignmentDeletedResult", "parameters": [ { "name": "secret", "in": "header", "required": false, "description": "Optional webhook secret configured in the flinkey Portal", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event was accepted and processed successfully" }, "204": { "description": "Webhook event was accepted and processed successfully without response body" }, "400": { "description": "Webhook payload is invalid or cannot be parsed\n\nRecommended handling: Reject the event and log sanitized diagnostics" }, "401": { "description": "Webhook secret is missing or invalid\n\nRecommended handling: Reject the event and do not process the payload" }, "403": { "description": "Webhook secret is invalid or request is not allowed\n\nRecommended handling: Reject the event and do not process the payload" }, "500": { "description": "Partner backend could not process the event\n\nRecommended handling: Retry or escalate according to partner webhook handling policy" } }, "security": [], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checksum": { "type": "string", "description": "Hash value generated from the payload of the initial request", "example": "abc123def456" }, "assignmentId": { "type": "number", "description": "Assignment database ID", "example": 77001 }, "customerId": { "type": "number", "description": "Customer database ID", "example": 99001 }, "operationSucceeded": { "type": "boolean", "description": "Indicates whether assignment deletion succeeded", "example": true }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message if the operation failed", "example": null } }, "required": [ "checksum", "assignmentId", "customerId", "operationSucceeded", "errorMessage" ] }, "example": { "checksum": "abc123def456", "assignmentId": 77001, "customerId": 99001, "operationSucceeded": true, "errorMessage": null } } } } } }, "/webhooks/assignmentUpdatedResult": { "post": { "tags": [ "Webhooks" ], "summary": "Assignment updated result", "description": "### Purpose\n\nReceive the asynchronous result of an assignment update request.\n\nThis webhook is sent by flinkey after an assignment update operation has been processed.\n\nAssignment update is asynchronous.\n\nThe initial API response confirms that the update request was accepted.\n\nThis webhook provides the final operation result.\n\n### When to use this operation\n\nUse this webhook when the partner backend needs to finalize local assignment state after updating an assignment.\n\nTypical situations:\n\n- confirming that an assignment update was processed successfully,\n- marking a local assignment update as successful,\n- marking a local assignment update as failed,\n- applying updated assignment start or end times locally,\n- storing `errorMessage` for troubleshooting,\n- reconciling pending assignment update requests,\n- deciding whether mobile access context can continue to be used.\n\nDo not mark an assignment update as successful before this webhook has been processed.\n\nDo not rely only on the initial assignment update API response for final assignment state.\n\n### Validation notes\n\nPROD validation result:\n\n- The configured update-result endpoint received an HTTP `POST` after the assignment update API returned `204 No Content`.\n- The incoming request used `Content-Type: application/json; charset=utf-8`.\n- The configured webhook secret was transmitted in the `secret` request header.\n- The successful payload contained `checksum`, numeric `assignmentId`, numeric `customerId`, `operationSucceeded: true`, `errorMessage: null` and the requested JSON Patch operation in `updateData`.\n- The webhook secret must be treated as sensitive and replaced if exposed during testing.\n\n### Async behavior\n\nThis webhook is the asynchronous result of `Update assignment`.\n\nThe partner backend should use this webhook to finalize local assignment update state.\n\nThe initial assignment update API response is not the final result.\n\n### Webhook result\n\nYes.\n\nThis entry describes the assignment updated result webhook.\n\nUse `operationSucceeded` to decide the final local update state.\n\n### Security notes\n\nNever log:\n\n- webhook secret,\n- full request headers,\n- backend bearer tokens,\n- API keys,\n- SDK Keys,\n- digital keys.\n\nValidate the `secret` header if a webhook secret is configured.\n\nDo not paste real webhook payloads containing sensitive identifiers into documentation, screenshots, tickets or AI prompts.\n\nUse placeholders in documentation and examples.\n\nThe `checksum` is not a replacement for webhook secret validation.\n\n### Endpoint ownership\n\nThe receiving endpoint is configured and operated by the integration partner.", "operationId": "webhooks.assignmentUpdatedResult", "parameters": [ { "name": "secret", "in": "header", "required": false, "description": "Optional webhook secret configured in the flinkey Portal", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook event was accepted and processed successfully" }, "204": { "description": "Webhook event was accepted and processed successfully without response body" }, "400": { "description": "Webhook payload is invalid or cannot be parsed\n\nRecommended handling: Reject the event and log sanitized diagnostics" }, "401": { "description": "Webhook secret is missing or invalid\n\nRecommended handling: Reject the event and do not process the payload" }, "403": { "description": "Webhook secret is invalid or request is not allowed\n\nRecommended handling: Reject the event and do not process the payload" }, "500": { "description": "Partner backend could not process the event\n\nRecommended handling: Retry or escalate according to partner webhook handling policy" } }, "security": [], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checksum": { "type": "string", "description": "Hash value generated from the payload of the initial request", "example": "abc123def456" }, "assignmentId": { "type": "number", "description": "Assignment database ID", "example": 77001 }, "customerId": { "type": "number", "description": "Customer database ID", "example": 99001 }, "operationSucceeded": { "type": "boolean", "description": "Indicates whether assignment update succeeded", "example": true }, "errorMessage": { "type": [ "string", "null" ], "description": "Error message if the operation failed", "example": null }, "updateData": { "type": "array", "items": { "type": "object" }, "description": "List of assignment update operations", "example": [ { "op": "replace", "path": "/end", "value": "2026-01-31T20:00:00Z" } ] }, "updateData.op": { "type": "string", "description": "Update operation. Allowed values are remove and replace" }, "updateData.path": { "type": "string", "description": "Assignment field that was updated" }, "updateData.value": { "type": [ "string", "null" ], "description": "New value for the selected path, or null where applicable" } }, "required": [ "checksum", "assignmentId", "customerId", "operationSucceeded", "errorMessage", "updateData", "updateData.op", "updateData.path", "updateData.value" ] }, "example": { "checksum": "abc123def456", "assignmentId": 77001, "customerId": 99001, "operationSucceeded": true, "errorMessage": null, "updateData": [ { "op": "replace", "path": "/end", "value": "2026-01-31T20:00:00Z" } ] } } } } } }, "/assignments": { "put": { "tags": [ "Assignments" ], "summary": "Create assignment", "description": "### Purpose\n\nCreate a new assignment in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nThis operation is used to create the access permission that allows a user to access a car.\n\nAssignment creation is asynchronous.\n\nThe API request confirms that the assignment creation request was accepted.\n\nThe final operation result is delivered through webhook.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to grant vehicle access to a user.\n\nTypical situations:\n\n- creating access for a booking,\n- granting a driver access to a car,\n- preparing mobile access for the partner app,\n- creating an unrestricted assignment,\n- creating a time-limited assignment for a defined access window.\n\nBefore creating an assignment, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `carId`,\n- the flinkey `userId`,\n- the intended assignment start time,\n- the intended assignment end time or unrestricted assignment behavior.\n\nDo not treat the assignment as active only because this API operation returned successfully.\n\nWait for the assignment created result webhook before marking the local assignment state as active.\n\n### Validation notes\n\nPROD validation result:\n\n- `PUT /assignments` returned `204 No Content` without a response body.\n- The direct API response represented request acceptance only.\n- A configured HTTPS webhook endpoint received the assignment created result as an HTTP `POST`.\n- The webhook contained the final numeric `assignmentId`, `carId`, `userId`, `customerId`, `checksum`, `operationSucceeded` and `errorMessage` fields.\n- `operationSucceeded` was `true` and `errorMessage` was `null` in the successful validation.\n- The created assignment was retrievable through the assignment read endpoints after successful webhook processing.\n\n### Async behavior\n\nAsynchronous.\n\nThe API response does not represent the final assignment creation result.\n\nThe partner backend must wait for the assignment created result webhook.\n\nThe local assignment should remain in a pending state until the webhook has been processed.\n\n### Webhook result\n\nYes.\n\nThis operation produces an assignment created result webhook.\n\nThe webhook result determines whether assignment creation succeeded or failed.\n\nUse `operationSucceeded` from the webhook payload to update the local assignment state.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nAssignment identifiers are environment-specific.\n\nDo not mix UAT and PROD assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.createAssignment", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Assignment creation request was accepted" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carId": { "type": "number", "description": "Database ID of the car", "example": 12345 }, "userId": { "type": "number", "description": "Database ID of the user", "example": 54321 }, "start": { "type": "string", "description": "Assignment start time in date-time format", "example": "2026-01-31T10:00:00Z" }, "end": { "type": [ "string", "null" ], "description": "Assignment end time in date-time format, or null for unrestricted assignment end", "example": "2026-01-31T18:00:00Z" }, "lifetime": { "type": [ "number", "null" ], "description": "Assignment lifetime in seconds", "example": 604800 }, "renewableAfter": { "type": [ "number", "null" ], "description": "Renewal timing in seconds", "example": 302400 } }, "required": [ "carId", "userId", "start", "end" ] }, "example": { "carId": 12345, "userId": 54321, "start": "2026-01-31T10:00:00Z", "end": "2026-01-31T18:00:00Z", "lifetime": 604800, "renewableAfter": 302400 } } } } } }, "/cars": { "put": { "tags": [ "Cars" ], "summary": "Create car", "description": "### Purpose\n\nCreate a new car in the selected customer context.\n\nA car represents the vehicle access object used by the flinkey API.\n\nFor developer integrations, the flinkey BLE Box is abstracted behind the `Car` concept.\n\nThe returned car ID can be used to inspect, update or assign access to the created car.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to create a new flinkey car for a partner vehicle.\n\nTypical situations:\n\n- initial vehicle setup,\n- adding a new vehicle to the partner fleet,\n- creating a flinkey car after no existing mapping was found,\n- preparing a vehicle before assignment creation,\n- onboarding a new vehicle type or fleet segment.\n\nIn most integrations, the partner backend should first check whether a flinkey car already exists for the partner vehicle.\n\nDo not create duplicate cars for the same partner vehicle without reconciliation.\n\nAfter successful creation, persist the mapping between the partner vehicle ID and the flinkey `carId`.\n\n### Validation notes\n\nPROD validation result:\n\n- `PUT /cars` with the minimal body `{ \"name\": \"{{CAR_NAME}}\" }` returned `201 Created`.\n- The response body contained only a numeric `id`.\n- A subsequent `GET /cars/{carId}` returned the supplied name.\n- Optional fields omitted during creation were returned as empty strings in the validated lookup response: `description`, `vin`, `licensePlate`, `brand` and `model`.\n- The operation completed synchronously and produced no webhook.\n\n### Async behavior\n\nSynchronous.\n\nThe new car ID is returned directly in the API response. Retrieve the complete car object with `GET /cars/{carId}`.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "cars.createCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Car was created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Newly created car database ID", "example": 12345 } } }, "example": { "id": 12345 } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Car name", "example": "VW Golf Fleet-01" }, "description": { "type": [ "string", "null" ], "description": "Optional car description" }, "vin": { "type": [ "string", "null" ], "description": "Vehicle identification number" }, "licensePlate": { "type": [ "string", "null" ], "description": "Vehicle license plate" }, "brand": { "type": [ "string", "null" ], "description": "Vehicle brand" }, "model": { "type": [ "string", "null" ], "description": "Vehicle model" } }, "required": [ "name" ] }, "example": { "name": "VW Golf Fleet-01" } } } } }, "get": { "tags": [ "Cars" ], "summary": "Get cars", "description": "### Purpose\n\nRetrieve cars available in the selected customer context.\n\nA car represents the vehicle access object used by the flinkey API.\n\nFor developer integrations, the flinkey BLE Box is abstracted behind the `Car` concept.\n\nThe returned car IDs can be used to create, update, inspect or assign access to cars.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve or search existing cars.\n\nTypical situations:\n\n- initial integration setup,\n- checking whether a car already exists before creating a new one,\n- validating the local mapping between partner vehicles and flinkey cars,\n- troubleshooting assignment creation,\n- reconciling partner vehicle records with flinkey car records.\n\nIn most integrations, the partner backend should persist a mapping between the partner vehicle ID and the flinkey `carId`.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /cars` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is an array.\n- `id` is returned as number.\n- `description`, `vin`, `licensePlate`, `brand` and `model` can contain empty strings, whitespace-only values, test/setup-specific values or `null` depending on the field and vehicle setup.\n- `$top` is supported.\n- `$skip` is supported.\n- `$filter` is supported.\n- `$orderby` is supported.\n- `$select` is not supported; using `$select` returns no result.\n\n### Async behavior\n\nSynchronous.\n\nThe cars are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "cars.getCars", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cars were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Car database ID" }, "name": { "type": "string", "description": "Car name" }, "description": { "type": [ "string", "null" ], "description": "Optional car description" }, "vin": { "type": [ "string", "null" ], "description": "Vehicle identification number" }, "licensePlate": { "type": [ "string", "null" ], "description": "Vehicle license plate" }, "brand": { "type": [ "string", "null" ], "description": "Vehicle brand" }, "model": { "type": [ "string", "null" ], "description": "Vehicle model" } } } }, "example": [ { "id": 12345, "name": "VW Golf Fleet-01", "description": "White VW Golf, 2024", "vin": "WVWZZZ1KZXW000001", "licensePlate": "B-FL 1234", "brand": "Volkswagen", "model": "Golf" } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/events": { "put": { "tags": [ "Events" ], "summary": "Create event", "description": "### Purpose\n\nCreate one open or close event for a car and user in the selected customer context.\n\nAn event represents an open or close event of a car.\n\nUse this operation only where partner-side event creation is explicitly required.\n\nIn standard access flows, partner integrations usually consume events rather than creating them directly.\n\nThis operation creates an operational event record.\n\nIt does not create access rights.\n\nIt does not unlock or lock a vehicle.\n\nIt does not create or change assignments.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to create an event record in flinkey.\n\nTypical situations:\n\n- creating an operational open or close event from a trusted backend process,\n- importing event data from a controlled integration workflow,\n- recording event information where the partner backend is the source of the event,\n- creating event records for advanced operational integrations.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nEvents are operational records and should not be treated as the primary access permission model.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\nBefore creating an event, the partner backend must have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `carId`,\n- the flinkey `userId`,\n- the event type,\n- the event timestamp,\n- the UTC event timestamp,\n- the user agent to be recorded.\n\n### Validation notes\n\n- `PUT /events` returned `201 Created` with a numeric event ID.\n- A minimal request without `latitude` and `longitude` was accepted.\n- The created event was retrieved successfully through `GET /events/{eventId}`; omitted coordinates were persisted as `null`.\n- `dateTime` was supplied as local wall-clock time and returned with an appended `Z`, while `utcDateTime` retained the explicitly supplied UTC value. Use `utcDateTime` for unambiguous time processing.\n- No event deletion endpoint is documented, so the validation event could not be removed through the public API.\n\n### Async behavior\n\nSynchronous.\n\nThe creation result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nEvent data can contain operational access history.\n\nTreat event records as sensitive operational data.\n\nCar, user and event identifiers are environment-specific.\n\nDo not mix UAT and PROD IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "events.createEvent", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Event was created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Database ID of the created event", "example": 12345 } } }, "example": { "id": 12345 } } } }, "400": { "description": "Event could not be created because type, dateTime, utcDateTime or userAgent is invalid or missing\n\nRecommended handling: Validate required request fields before retrying" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager was not found, the car was not found for the selected customer, or the user was not found for the selected customer\n\nRecommended handling: Check credentials, token context, Customer-ID, local carId mapping, local userId mapping and environment" }, "415": { "description": "Request media type is not supported\n\nRecommended handling: Send Content-Type: application/json" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Advanced", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dateTime": { "type": "string", "format": "date-time", "description": "Event date and time", "example": "2026-07-01T10:15:30.000" }, "utcDateTime": { "type": "string", "format": "date-time", "description": "Event date and time in UTC", "example": "2026-07-01T08:15:30.000Z" }, "userId": { "type": "integer", "description": "Database ID of the user associated with the event", "example": 67890 }, "carId": { "type": "integer", "description": "Database ID of the car associated with the event", "example": 123 }, "type": { "type": "string", "description": "Event type. Documented values are CarOpened and CarClosed", "example": "CarOpened" }, "userAgent": { "type": "string", "description": "User agent to record for the event", "example": "partner-backend" }, "latitude": { "type": [ "number", "null" ], "description": "Latitude, if available", "example": 51.2562 }, "longitude": { "type": [ "number", "null" ], "description": "Longitude, if available", "example": 7.1508 } }, "required": [ "dateTime", "utcDateTime", "userId", "carId", "type", "userAgent" ] }, "example": { "dateTime": "2026-07-01T10:15:30.000", "utcDateTime": "2026-07-01T08:15:30.000Z", "userId": 67890, "carId": 123, "type": "CarOpened", "userAgent": "partner-backend", "latitude": 51.2562, "longitude": 7.1508 } } } } } }, "/groups": { "put": { "tags": [ "Grouping" ], "summary": "Create group", "description": "### Purpose\n\nCreate a new group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a new group must be created before assigning entities to it.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to create a group.\n\nTypical situations:\n\n- creating a group for operational administration,\n- preparing group-based assignment of cars,\n- preparing group-based assignment of users,\n- preparing group-based assignment of services,\n- preparing group-based assignment of products,\n- creating a group for reconciliation or support workflows,\n- setting up a customer-specific grouping structure.\n\nBefore creating a group, check whether a group with the intended name already exists.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Validation notes\n\n- `PUT /groups` with a JSON object containing `name` returned `201 Created` and a numeric group ID.\n- Persistence was verified through `GET /groups`.\n- Repeating the create request with the same name returned `409 Conflict` and a plain JSON string stating that a group with the same name already exists.\n- The validation group remains temporary and must be deleted after the complete Grouping validation block.\n\n### Async behavior\n\nSynchronous.\n\nThe group creation result is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.createGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Group was created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Database ID of the created group", "example": 200 } } }, "example": { "id": 200 } } } }, "400": { "description": "Group could not be created because no group name was provided\n\nRecommended handling: Check that name is present and not empty" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "409": { "description": "A group with the same name already exists\n\nRecommended handling: Retrieve existing groups and reconcile local group mapping before retrying" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group to create", "example": "Fleet Berlin" } }, "required": [ "name" ] }, "example": { "name": "Fleet Berlin" } } } } }, "get": { "tags": [ "Grouping" ], "summary": "Get groups", "description": "### Purpose\n\nRetrieve groups available in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping, lookup, reconciliation and support workflows where grouped entities must be retrieved.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve available groups for a customer.\n\nTypical situations:\n\n- listing groups for operational tooling,\n- checking whether a group exists,\n- preparing follow-up calls for cars, users, services or products of a group,\n- supporting grouping-based administration workflows,\n- reconciling group records with partner or support records,\n- validating group setup before assigning entities to a group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse grouping operations where the integration or operational process explicitly works with grouped cars, users, services or products.\n\n### Validation notes\n\n- The initial request returned `200 OK` with an empty array.\n- After controlled group creation, the same operation returned the created group as an object containing numeric `id` and string `name`.\n- No OData query options were used or validated.\n\n### Async behavior\n\nSynchronous.\n\nThe groups are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.getGroups", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Groups were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Group database ID" }, "name": { "type": "string", "description": "Group name" } } } }, "example": [ { "id": 200, "name": "Fleet Berlin" } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/users": { "put": { "tags": [ "Users" ], "summary": "Create user", "description": "### Purpose\n\nCreate a new user in the selected customer context.\n\nA user represents the access identity that can receive assignments for cars.\n\nFor standard full partner integrations, the partner backend should usually create or resolve an anonymous flinkey user.\n\nAnonymous users are used as technical access identities for partner app based integrations.\n\nAnonymous users cannot sign in to the flinkey App for Android or iOS.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to create a new flinkey user for vehicle access.\n\nTypical situations:\n\n- initial customer or driver setup,\n- creating an anonymous user for a partner app based integration,\n- preparing a user before assignment creation,\n- mapping a partner customer or driver to a flinkey user,\n- onboarding a new access identity for future vehicle assignments.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nDo not create a new anonymous user for every booking unless that is the intended operating model.\n\nBefore creating a user, check whether a local user mapping already exists.\n\n### Validation notes\n\nPROD validation result:\n\n- `PUT /users` with `{ \"type\": \"Anonymous\" }` returned `201 Created`.\n- The anonymous-user response contained a numeric `id` and `password: null`.\n- A subsequent user lookup returned an internally generated technical e-mail address, `firstName: \"unknown\"` and `lastName: null`.\n- Partner-provided e-mail and profile fields were accepted but ignored when `type` was `Anonymous`.\n- `PUT /users` with `type: \"Normal\"`, e-mail address and profile data returned `201 Created`.\n- The normal-user response contained a numeric `id` and a generated password string.\n- A subsequent user lookup returned the supplied e-mail address, first name and last name.\n- Repeating normal-user creation with the same e-mail address returned `409 Conflict` with the message `An user with the given e-mail address already exists.`\n- All public examples use placeholders; generated passwords and real user data must not be documented.\n\n### Async behavior\n\nSynchronous.\n\nThe API returns the created user ID and a password value. Use `GET /users/{userId}` to retrieve the persisted user profile.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers,\n- returned password values.\n\nUser identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "users.createUser", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "User was created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "User database ID", "example": 54321 }, "password": { "type": [ "string", "null" ], "description": "Generated initial password for a normal user; null for an anonymous user in the validated responses", "example": null } } }, "example": { "id": 54321, "password": null } } } }, "400": { "description": "Request body is invalid\n\nRecommended handling: Validate the request body for the selected user type" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "409": { "description": "A normal user with the given e-mail address already exists\n\nRecommended handling: Resolve and reuse the existing user instead of creating a duplicate" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailAddress": { "type": "string", "description": "Provide for a normal user. It is not required for the validated anonymous-user request." }, "userData": { "type": "object", "description": "Provide for a normal user. It is not required for the validated anonymous-user request." }, "userData.firstName": { "type": "string", "description": "First name for a normal user" }, "userData.lastName": { "type": "string", "description": "Last name for a normal user" }, "password": { "type": [ "string", "null" ], "description": "Optional password input; not used in the validated requests" }, "type": { "type": "string", "description": "Use Anonymous or Normal", "example": "Anonymous" } } }, "example": { "type": "Anonymous" } } } } }, "get": { "tags": [ "Users" ], "summary": "Get users", "description": "### Purpose\n\nRetrieve users available in the selected customer context.\n\nA user represents the access identity that can receive assignments for cars.\n\nFor standard full partner integrations, the partner backend usually works with anonymous flinkey users.\n\nThe returned user IDs can be used to inspect, reconcile or assign access to users.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve or search existing users.\n\nTypical situations:\n\n- initial integration setup,\n- checking whether a user already exists before creating a new one,\n- validating the local mapping between partner customers or drivers and flinkey users,\n- troubleshooting assignment creation,\n- reconciling partner customer or driver records with flinkey user records.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nDo not create duplicate anonymous users without checking existing mappings first.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /users` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response was an array of user objects.\n- `id` was returned as a number.\n- `emailAddress` was returned as a string in the validated response set.\n- `userData` was returned as an object containing `firstName` and `lastName` in the validated response set.\n- `$top`, `$skip`, `$orderby` and `$filter` were successfully validated.\n- `$filter` was validated with the top-level field `id` and with the nested OData path `userData/firstName`.\n- `$select` is not supported by the flinkey API and must not be used.\n- No default response ordering is guaranteed; use `$orderby` when deterministic ordering is required.\n- Production names and email addresses used during validation were not copied into this documentation.\n\n### Async behavior\n\nSynchronous.\n\nThe users are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUser identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "users.getUsers", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Users were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "User database ID" }, "emailAddress": { "type": "string", "description": "E-mail address of the user" }, "userData": { "type": "object", "description": "User profile data" }, "userData.firstName": { "type": [ "string", "null" ], "description": "First name" }, "userData.lastName": { "type": [ "string", "null" ], "description": "Last name" } } } }, "example": [ { "id": 54321, "emailAddress": "user@example.com", "userData": { "firstName": "Max", "lastName": "Mustermann" } } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/assignments/{assignmentId}": { "delete": { "tags": [ "Assignments" ], "summary": "Delete assignment", "description": "### Purpose\n\nDelete an existing assignment in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nUse this operation to remove an existing access permission.\n\nAssignment deletion is asynchronous.\n\nThe API request confirms that the assignment deletion request was accepted.\n\nThe final operation result is delivered through webhook.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to remove an existing assignment.\n\nTypical situations:\n\n- ending a booking-related access permission,\n- removing vehicle access from a user,\n- deleting an incorrect assignment,\n- cleaning up test assignments,\n- retiring an access permission after reconciliation.\n\nBefore deleting an assignment, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `assignmentId`,\n- the intended local assignment state,\n- whether the assignment is still required by a partner process.\n\nDo not treat the assignment deletion as final only because this API operation returned successfully.\n\nWait for the assignment deleted result webhook before marking the local assignment as deleted.\n\n### Validation notes\n\nPROD validation result:\n\n- `DELETE /assignments/{assignmentId}` returned `204 No Content` without a response body.\n- The configured assignment-deleted webhook received an HTTP `POST`.\n- The webhook contained `checksum`, numeric `assignmentId`, numeric `customerId`, `operationSucceeded` and `errorMessage`.\n- `operationSucceeded` was `true` and `errorMessage` was `null` in the successful validation.\n- A subsequent assignment lookup confirmed that the assignment was no longer available.\n\n### Async behavior\n\nAsynchronous.\n\nThe API response does not represent the final assignment deletion result.\n\nThe partner backend must wait for the assignment deleted result webhook.\n\nThe local assignment should remain in a pending deletion state until the webhook has been processed.\n\n### Webhook result\n\nYes.\n\nThis operation produces an assignment deleted result webhook.\n\nThe webhook result determines whether assignment deletion succeeded or failed.\n\nUse `operationSucceeded` from the webhook payload to update the local assignment state.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nAssignment identifiers are environment-specific.\n\nDo not mix UAT and PROD assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.deleteAssignment", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "assignmentId", "in": "path", "required": true, "description": "Database ID of the assignment", "schema": { "type": "number" } } ], "responses": { "204": { "description": "Assignment deletion request was accepted" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or assignment was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local assignmentId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" }, "get": { "tags": [ "Assignments" ], "summary": "Get assignment", "description": "### Purpose\n\nRetrieve one specific assignment by assignment ID in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nUse this operation to validate or inspect an existing assignment.\n\nThe returned assignment data can be used for reconciliation, support workflows or backend state validation.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve one specific flinkey assignment.\n\nTypical situations:\n\n- validating a local assignment mapping,\n- checking whether a mapped assignment still exists,\n- troubleshooting mobile access,\n- troubleshooting webhook processing,\n- reconciling partner access records with flinkey assignment records,\n- inspecting assignment start and end times,\n- validating assignment lifetime and renewal data.\n\nIn most integrations, the partner backend should persist a mapping between the partner access context and the flinkey `assignmentId`.\n\nUse the mapped `assignmentId` to retrieve the correct flinkey assignment.\n\nDo not create a new assignment when an existing mapped assignment should be used or updated.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /assignments/{assignmentId}` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is a single assignment object.\n- `id`, `carId` and `userId` are returned as numbers.\n- `start` is returned as UTC timestamp string.\n- `end` may be `null`.\n- `lifetime` is returned as number when provided.\n- `renewableAfter` may be `null`.\n- OData collection query options such as `$filter`, `$orderby`, `$count`, `$skip` and `$top` are not supported because this endpoint returns a single resource, not a collection.\n- `$select` was tested and resulted in a timeout; do not use `$select` for this endpoint.\n- Use assignment collection endpoints for OData-based filtering, ordering, paging or collection query behavior.\n\n### Async behavior\n\nSynchronous.\n\nThe assignment is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nAssignment identifiers are environment-specific.\n\nDo not mix UAT and PROD assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.getAssignment", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "assignmentId", "in": "path", "required": true, "description": "Database ID of the assignment", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Assignment was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Assignment database ID", "example": 10001 }, "carId": { "type": "number", "description": "Car database ID assigned to the user", "example": 20001 }, "userId": { "type": "number", "description": "User database ID assigned to the car", "example": 30001 }, "start": { "type": "string", "description": "Assignment start time as UTC timestamp", "example": "2026-02-10T10:11:02.240Z" }, "end": { "type": [ "string", "null" ], "description": "Assignment end time as UTC timestamp, or null for open-ended access", "example": null }, "lifetime": { "type": [ "number", "null" ], "description": "Assignment lifetime in seconds", "example": 604800 }, "renewableAfter": { "type": [ "number", "null" ], "description": "Renewal timing information, if provided", "example": null } } }, "example": { "id": 10001, "carId": 20001, "userId": 30001, "start": "2026-02-10T10:11:02.240Z", "end": null, "lifetime": 604800, "renewableAfter": null } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or assignment was not found\n\nRecommended handling: Check credentials, Customer-ID and local assignmentId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" }, "patch": { "tags": [ "Assignments" ], "summary": "Update assignment", "description": "### Purpose\n\nUpdate an existing assignment in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nUse this operation to change an existing access permission.\n\nAssignment updates are asynchronous.\n\nThe API request confirms that the assignment update request was accepted.\n\nThe final operation result is delivered through webhook.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to update an existing assignment.\n\nTypical situations:\n\n- changing assignment start time,\n- changing assignment end time,\n- extending or shortening vehicle access,\n- changing the assigned car,\n- changing the assigned user,\n- updating lifetime or renewal behavior,\n- correcting assignment data after reconciliation.\n\nBefore updating an assignment, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `assignmentId`,\n- the intended update operation,\n- the expected local assignment state.\n\nDo not treat the assignment update as final only because this API operation returned successfully.\n\nWait for the assignment updated result webhook before marking the local assignment update as successful.\n\n### Validation notes\n\nPROD validation result:\n\n- `PATCH /assignments/{assignmentId}` with a JSON Patch `replace` operation for `/end` returned `204 No Content` without a response body.\n- The configured assignment-updated webhook received an HTTP `POST` containing the same patch operation in `updateData`.\n- The webhook contained `checksum`, numeric `assignmentId`, numeric `customerId`, `operationSucceeded`, `errorMessage` and `updateData`.\n- `operationSucceeded` was `true` and `errorMessage` was `null` in the successful validation.\n- A configured webhook secret was transmitted in the `secret` request header and was visible to the receiving test endpoint.\n- A subsequent assignment lookup confirmed that the updated end time was persisted.\n\n### Async behavior\n\nAsynchronous.\n\nThe API response does not represent the final assignment update result.\n\nThe partner backend must wait for the assignment updated result webhook.\n\nThe local assignment should remain in a pending update state until the webhook has been processed.\n\n### Webhook result\n\nYes.\n\nThis operation produces an assignment updated result webhook.\n\nThe webhook result determines whether assignment update succeeded or failed.\n\nUse `operationSucceeded` from the webhook payload to update the local assignment state.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nAssignment identifiers are environment-specific.\n\nDo not mix UAT and PROD assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.updateAssignment", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "assignmentId", "in": "path", "required": true, "description": "Database ID of the assignment", "schema": { "type": "number" } } ], "responses": { "204": { "description": "Assignment update request was accepted" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "description": "Update operation. Allowed values are remove and replace" }, "path": { "type": "string", "description": "Assignment field to update" }, "value": { "type": [ "string", "null" ], "description": "New value for the selected path, or null where applicable" } }, "required": [ "op", "path", "value" ] } }, "example": [ { "op": "replace", "path": "/end", "value": "2026-01-31T20:00:00Z" } ] } } } } }, "/cars/{carId}": { "delete": { "tags": [ "Cars" ], "summary": "Delete car", "description": "### Purpose\n\nDelete an existing car from the selected customer context.\n\nA car represents the vehicle access object used by the flinkey API.\n\nFor developer integrations, the flinkey BLE Box is abstracted behind the `Car` concept.\n\nUse this operation only when a car should no longer be available for future access or assignment operations.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to remove an existing flinkey car.\n\nTypical situations:\n\n- a vehicle is removed from the partner fleet,\n- a test car should be cleaned up,\n- an incorrectly created car should be removed,\n- a vehicle mapping is being retired,\n- a car should no longer be used for future assignment creation.\n\nBefore deleting a car, check whether the car is still referenced by active partner processes.\n\nIn most integrations, the partner backend should persist a mapping between the partner vehicle ID and the flinkey `carId`.\n\nAfter successful deletion, update or remove the local mapping.\n\nDo not delete a car only because a customer currently has no active assignment.\n\n### Validation notes\n\nPROD validation result:\n\n- `DELETE /cars/{carId}` returned `204 No Content` without a response body.\n- A subsequent `GET /cars/{carId}` returned `404 Not Found`.\n- The post-delete lookup message was `Unable to find a car for the given carId which is assigned to the given customerId.`\n- The full create, update, get and delete lifecycle was repeated with a second controlled test car to confirm the response codes.\n- The operation completed synchronously and produced no webhook.\n\n### Async behavior\n\nSynchronous.\n\nThe delete result is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "cars.deleteCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car to delete", "schema": { "type": "number" } } ], "responses": { "204": { "description": "Car was deleted successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or car was not found\n\nRecommended handling: Check credentials, Customer-ID and local carId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" }, "get": { "tags": [ "Cars" ], "summary": "Get car", "description": "### Purpose\n\nRetrieve one specific car by car ID in the selected customer context.\n\nA car represents the vehicle access object used by the flinkey API.\n\nFor developer integrations, the flinkey BLE Box is abstracted behind the `Car` concept.\n\nUse this operation when the partner backend already knows the flinkey `carId` and needs to retrieve the current car data.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to inspect or validate one specific car.\n\nTypical situations:\n\n- validating a stored partner vehicle to flinkey car mapping,\n- checking whether a stored `carId` still exists,\n- retrieving car metadata before creating an assignment,\n- troubleshooting assignment creation,\n- reconciling local vehicle data with flinkey car data.\n\nIn most integrations, the partner backend should persist a mapping between the partner vehicle ID and the flinkey `carId`.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /cars/{carId}` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is a single car object.\n- `id` is returned as number.\n- `description`, `vin`, `name`, `licensePlate`, `brand` and `model` are returned as string values.\n- Metadata fields such as `vin` may be empty depending on vehicle setup and data quality.\n- OData collection query options such as `$filter`, `$orderby`, `$count`, `$skip` and `$top` are not supported because this endpoint returns a single resource, not a collection.\n- `$select` was tested and resulted in a timeout; do not use `$select` for this endpoint.\n- Use `GET /cars` for OData-based filtering, ordering, paging or collection query behavior.\n\n### Async behavior\n\nSynchronous.\n\nThe car is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "cars.getCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Car was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Car database ID", "example": 123 }, "name": { "type": "string", "description": "Car name", "example": "VW Golf Fleet-01" }, "description": { "type": [ "string", "null" ], "description": "Optional car description", "example": "White VW Golf, 2024" }, "vin": { "type": [ "string", "null" ], "description": "Vehicle identification number", "example": "WVWZZZ1KZXW000001" }, "licensePlate": { "type": [ "string", "null" ], "description": "Vehicle license plate", "example": "B-FL 1234" }, "brand": { "type": [ "string", "null" ], "description": "Vehicle brand", "example": "Volkswagen" }, "model": { "type": [ "string", "null" ], "description": "Vehicle model", "example": "Golf" } } }, "example": { "id": 123, "name": "VW Golf Fleet-01", "description": "White VW Golf, 2024", "vin": "WVWZZZ1KZXW000001", "licensePlate": "B-FL 1234", "brand": "Volkswagen", "model": "Golf" } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or requested car could not be found for the selected customer context\n\nRecommended handling: Check API Manager setup, Customer-ID, carId and local vehicle mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" }, "patch": { "tags": [ "Cars" ], "summary": "Update car", "description": "### Purpose\n\nUpdate an existing car in the selected customer context.\n\nA car represents the vehicle access object used by the flinkey API.\n\nFor developer integrations, the flinkey BLE Box is abstracted behind the `Car` concept.\n\nUse this operation to update car metadata after the car has already been created.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to update an existing flinkey car.\n\nTypical situations:\n\n- vehicle metadata changed,\n- license plate changed,\n- VIN was added or corrected,\n- brand or model information was added,\n- car name or description was updated,\n- partner vehicle records were reconciled with flinkey car records.\n\nIn most integrations, the partner backend should persist a mapping between the partner vehicle ID and the flinkey `carId`.\n\nUse the mapped `carId` to update the correct flinkey car.\n\nDo not create a new car when the existing car should be updated.\n\n### Validation notes\n\nPROD validation result:\n\n- The Developer Page and PROD behavior confirmed `PATCH /cars/{carId}`. The previously documented `POST` method returned `404 Not Found`.\n- A normal JSON object sent to the PATCH endpoint returned `400 Bad Request` because the JSON Patch document could not be parsed.\n- A JSON Patch array with `Content-Type: application/json-patch+json` returned `204 No Content` without a response body.\n- `replace` operations were validated for `name`, `description`, `vin`, `licensePlate`, `brand` and `model`.\n- A subsequent `GET /cars/{carId}` returned all updated values.\n- The operation completed synchronously and produced no webhook.\n\n### Async behavior\n\nSynchronous.\n\nThe API returns `204 No Content`. Retrieve the complete updated car object with `GET /cars/{carId}`.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "cars.updateCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car to update", "schema": { "type": "number" } } ], "responses": { "204": { "description": "Car was updated successfully" }, "400": { "description": "JSON Patch document is malformed or cannot be parsed\n\nRecommended handling: Use a JSON Patch array and Content-Type: application/json-patch+json" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or car was not found\n\nRecommended handling: Check credentials, Customer-ID and local carId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json-patch+json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "description": "JSON Patch operation; replace was validated" }, "path": { "type": "string", "description": "Car field path to update" }, "value": { "type": [ "string", "null" ], "description": "New value for the selected field" } }, "required": [ "op", "path", "value" ] } }, "example": [ { "op": "replace", "path": "/name", "value": "VW Golf Fleet-01" } ] } } } } }, "/groups/{groupId}": { "delete": { "tags": [ "Grouping" ], "summary": "Delete group", "description": "### Purpose\n\nDelete one specific group from the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation only when an existing group is no longer required and all relations to the group have already been removed.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to delete a group.\n\nTypical situations:\n\n- removing an obsolete operational group,\n- cleaning up test or setup groups,\n- deleting a group after migration or restructuring,\n- removing a wrongly created group,\n- cleaning up grouping structures after reconciliation.\n\nBefore deleting a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- whether the group exists,\n- whether the group still has related cars,\n- whether the group still has related users,\n- whether the group still has related services,\n- whether the group still has related products.\n\nA group cannot be deleted while relations to the group still exist.\n\nRemove all relations to cars, users, services and products before deleting the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- After all car, product, service and user relations had been removed, PROD returned `204 No Content` with an empty body. A control `GET /groups` confirmed that the group was absent.\n\n### Async behavior\n\nSynchronous.\n\nThe delete result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\nDeleting a group does not replace assignment lifecycle operations.\n\nIf access permissions must be changed, use the appropriate assignment operations.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.deleteGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Group was deleted successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "409": { "description": "Group could not be deleted because existing relations to the group still exist\n\nRecommended handling: Remove all relations to the group and retry only after reconciliation" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" }, "patch": { "tags": [ "Grouping" ], "summary": "Update group", "description": "### Purpose\n\nUpdate the name of one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where an existing group must be renamed.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to update a group name.\n\nTypical situations:\n\n- renaming an operational group,\n- correcting a group name,\n- aligning group names with partner-side structures,\n- maintaining group-based administration workflows,\n- updating group names after customer-side naming changes,\n- cleaning up group names after reconciliation.\n\nBefore updating a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the intended new group name,\n- whether the group exists,\n- whether the new name is valid,\n- whether the new name would conflict with operational naming rules.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\n### Validation notes\n\n- `PATCH /groups/{groupId}` with a JSON Patch `replace` operation for `/name` returned `204 No Content`.\n- `Content-Type: application/json-patch+json` was accepted and is the validated media type.\n- The renamed group was retrieved through `GET /groups`; the group ID remained unchanged.\n\n### Async behavior\n\nSynchronous.\n\nThe group update result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.updateGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Group was updated successfully" }, "400": { "description": "Group name is null, empty, whitespace or longer than the allowed maximum length\n\nRecommended handling: Validate the new group name before sending the request" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID and local groupId mapping" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json-patch+json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json-patch+json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "description": "Operation to perform. Documented value: replace" }, "path": { "type": "string", "description": "Field to update. Documented value: /name" }, "value": { "type": [ "string", "null" ], "description": "New group name" } }, "required": [ "op", "path", "value" ] } }, "example": [ { "op": "replace", "path": "/name", "value": "Fleet Berlin" } ] } } } } }, "/cars/{carId}/assignments": { "get": { "tags": [ "Assignments" ], "summary": "Get assignments of car", "description": "### Purpose\n\nRetrieve assignments for one specific car in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nUse this operation to inspect which assignments exist for a specific car.\n\nThe returned assignment data can be used for reconciliation, support workflows or backend state validation.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve assignments related to one specific flinkey car.\n\nTypical situations:\n\n- checking which users currently have access to a car,\n- validating assignment state for a vehicle,\n- troubleshooting mobile access for a specific car,\n- troubleshooting assignment creation,\n- reconciling partner vehicle access records with flinkey assignment records,\n- inspecting assignment start and end times for a vehicle.\n\nIn most integrations, the partner backend should persist a mapping between the partner vehicle and the flinkey `carId`.\n\nUse the mapped `carId` to retrieve assignments for the correct flinkey car.\n\nDo not create new assignments before checking whether the intended access already exists, if duplicate access would cause operational issues.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /cars/{carId}/assignments` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is an array.\n- `id` is returned as number.\n- `userId` is returned as number.\n- `start` is returned as UTC timestamp string.\n- `end` may be `null`.\n- `lifetime` is returned as number when provided.\n- `renewableAfter` may be `null`.\n- The response model does not include `carId`; the car context is defined by the path parameter.\n- `$top`, `$skip`, `$filter` and `$orderby` are supported.\n- `$select` is not recommended and must not be used.\n\n### Async behavior\n\nSynchronous.\n\nThe assignments are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nCar and assignment identifiers are environment-specific.\n\nDo not mix UAT and PROD car IDs or assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.getAssignmentsOfCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Assignments of the car were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Assignment database ID" }, "userId": { "type": "number", "description": "User database ID assigned to the car" }, "start": { "type": "string", "description": "Assignment start time as UTC timestamp" }, "end": { "type": [ "string", "null" ], "description": "Assignment end time as UTC timestamp, or null for open-ended access" }, "lifetime": { "type": [ "number", "null" ], "description": "Assignment lifetime in seconds, if provided" }, "renewableAfter": { "type": [ "number", "null" ], "description": "Renewal timing information, if provided" } } } }, "example": [ { "id": 10001, "userId": 30001, "start": "2026-02-10T10:11:02.240Z", "end": null, "lifetime": 604800, "renewableAfter": null } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or assignment data was not found\n\nRecommended handling: Check credentials, Customer-ID and local carId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/users/{userId}/assignments": { "get": { "tags": [ "Assignments" ], "summary": "Get assignments of user", "description": "### Purpose\n\nRetrieve assignments for one specific user in the selected customer context.\n\nAn assignment grants access from a user to a car for a defined time range.\n\nUse this operation to inspect which assignments exist for a specific user.\n\nThe returned assignment data can be used for reconciliation, support workflows or backend state validation.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve assignments related to one specific flinkey user.\n\nTypical situations:\n\n- checking which cars a user currently has access to,\n- validating assignment state for a user,\n- troubleshooting mobile access for a specific user,\n- troubleshooting assignment creation,\n- reconciling partner customer or driver access records with flinkey assignment records,\n- inspecting assignment start and end times for a user.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nUse the mapped `userId` to retrieve assignments for the correct flinkey user.\n\nDo not create new assignments before checking whether the intended access already exists, if duplicate access would cause operational issues.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /users/{userId}/assignments` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is an array.\n- `id` is returned as number.\n- `carId` is returned as number.\n- `start` is returned as UTC timestamp string.\n- `end` may be `null`.\n- `lifetime` is returned as number when provided.\n- `renewableAfter` may be a number or `null`.\n- The response model does not include `userId`; the user context is defined by the path parameter.\n- `$top`, `$skip`, `$filter` and `$orderby` are supported.\n- `$select` is not supported by the flinkey API and must not be used.\n- No default response order should be assumed; use `$orderby` when order matters.\n\n### Async behavior\n\nSynchronous.\n\nThe assignments are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUser and assignment identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs or assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "assignments.getAssignmentsOfUser", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Database ID of the user", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Assignments of the user were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Assignment database ID" }, "carId": { "type": "number", "description": "Car database ID assigned to the user" }, "start": { "type": "string", "description": "Assignment start time as UTC timestamp" }, "end": { "type": [ "string", "null" ], "description": "Assignment end time as UTC timestamp, or null for open-ended access" }, "lifetime": { "type": [ "number", "null" ], "description": "Assignment lifetime in seconds, if provided" }, "renewableAfter": { "type": [ "number", "null" ], "description": "Renewal-related value returned by the API, if applicable" } } } }, "example": [ { "id": 10001, "carId": 20001, "start": "2026-01-31T10:00:00.000Z", "end": null, "lifetime": 604800, "renewableAfter": null }, { "id": 10002, "carId": 20002, "start": "2026-02-01T08:00:00.000Z", "end": "2026-02-01T18:00:00.000Z", "lifetime": 604800, "renewableAfter": null } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or user assignment data was not found\n\nRecommended handling: Check credentials, Customer-ID and local userId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/brands": { "get": { "tags": [ "Keyfob" ], "summary": "Get brands", "description": "### Purpose\n\nRetrieve available vehicle brands for keyfob matching.\n\nThe keyfob area helps determine which key fits to a car.\n\nUse this operation as the first lookup step when a partner or operational backend needs to identify available keyfob data by vehicle brand.\n\nThe response is a list of brand names.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve available brands before looking up matching keys.\n\nTypical situations:\n\n- preparing a keyfob selection workflow,\n- supporting operational keybed or keyfob matching,\n- allowing a user or support agent to select a vehicle brand,\n- validating whether a vehicle brand is available in the keyfob data,\n- preparing a follow-up call to retrieve keys of a specific brand.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse keyfob operations for key matching, setup and support workflows.\n\n### Validation notes\n\n- The request succeeded with `200 OK` without a `Customer-ID` header.\n- The response was a direct array of uppercase brand-name strings.\n- `$top`, `$skip`, `$orderby=$it desc` and `$filter=$it eq 'BMW'` were validated successfully.\n- Brand names can contain spaces and must be URL-encoded when used as the `brand` path parameter.\n- Case-insensitive matching was not validated and must not be assumed.\n\n### Async behavior\n\nSynchronous.\n\nThe brand list is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "keyfob.getBrands", "parameters": [ { "name": "Customer-ID", "in": "header", "required": false, "description": "Not required for this operation", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Brands were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string", "description": "Vehicle brand name" } } } }, "example": [ "Volkswagen" ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/products/{productId}/cars": { "get": { "tags": [ "Products" ], "summary": "Get car of product", "description": "### Purpose\n\nRetrieve the car assigned to one specific product in the selected customer context.\n\nA product represents a flinkey hardware product assigned to the customer context.\n\nA car is the API abstraction used for vehicle-related access flows.\n\nUse this operation for operational lookup, reconciliation and support workflows where the relationship between a product and a car must be inspected.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve the car assigned to a specific product.\n\nTypical situations:\n\n- checking which car is assigned to a product,\n- reconciling hardware setup with car records,\n- supporting operational troubleshooting,\n- validating product-to-car assignment,\n- identifying car data from a known product reference,\n- checking vehicle metadata such as VIN, license plate, brand or model.\n\nFor standard access flows, the partner backend should usually work with `Car`, `User` and `Assignment`.\n\nUse this operation only where product-level lookup is required.\n\n### Validation notes\n\n- The base request returned `200 OK` with one car object despite the plural `/cars` path.\n- The returned car ID matched the `carId` exposed by the related product.\n- `description` was observed as `null`; `vin`, `brand` and `model` were observed as empty strings.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n\n### Async behavior\n\nSynchronous.\n\nThe car assigned to the product is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct and car identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs or car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "products.getCarOfProduct", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Database ID of the product", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Car assigned to the product was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Car database ID", "example": 12345 }, "name": { "type": "string", "description": "Car name", "example": "VW Golf Fleet-01" }, "description": { "type": [ "string", "null" ], "description": "Car description", "example": "White VW Golf, 2024" }, "vin": { "type": [ "string", "null" ], "description": "Vehicle identification number", "example": "WVWZZZ1KZXW000001" }, "licensePlate": { "type": [ "string", "null" ], "description": "Vehicle license plate", "example": "B-FL 1234" }, "brand": { "type": [ "string", "null" ], "description": "Vehicle brand", "example": "Volkswagen" }, "model": { "type": [ "string", "null" ], "description": "Vehicle model", "example": "Golf" } } }, "example": { "id": 12345, "name": "VW Golf Fleet-01", "description": "White VW Golf, 2024", "vin": "WVWZZZ1KZXW000001", "licensePlate": "B-FL 1234", "brand": "Volkswagen", "model": "Golf" } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, product or assigned car was not found\n\nRecommended handling: Check credentials, Customer-ID, local productId reference and product-to-car assignment" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "Get customers", "description": "### Purpose\n\nRetrieve all customer contexts that the authenticated API Manager is authorized to access.\n\nThis is the first protected endpoint used after token retrieval. It verifies the effective API Manager scope and returns the customer IDs that can be used for subsequent customer-scoped requests.\n\nThe request does not require a `Customer-ID` header. The response is an array because an API Manager can reach one or more customer contexts.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to discover or validate the customer contexts available to the authenticated API Manager.\n\nTypical situations:\n\n- initial integration setup,\n- backend configuration validation,\n- checking which customer contexts the API Manager can reach,\n- verifying UAT or PROD configuration,\n- retrieving the IDs and names available for subsequent customer-scoped requests,\n- troubleshooting authorization or customer-context issues.\n\nIn most integrations, the intended `Customer-ID` should be selected from this response and then configured for subsequent customer-scoped requests.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /customers` was successfully executed with `flinkey-API-Key` and `Authorization: Bearer {{accessToken}}`, without a `Customer-ID` header.\n- The endpoint returned all customer contexts reachable by the authenticated API Manager.\n- The response is an array.\n- `id` is returned as number.\n- `name` is returned as string.\n- `$top` is supported.\n- `$skip` is supported.\n- `$filter` is supported.\n- `$orderby` is supported.\n- `$select` is not supported; using `$select` returns no result.\n\n### Async behavior\n\nSynchronous.\n\nThe customer context is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "customers.getCustomers", "parameters": [ { "name": "Customer-ID", "in": "header", "required": false, "description": "Not required; omitting it allows the endpoint to list all customer contexts reachable by the API Manager", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reachable customer contexts were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Customer database ID" }, "name": { "type": "string", "description": "Customer name" } } } }, "example": [ { "id": 123, "name": "Example Fleet GmbH" } ] } } }, "400": { "description": "Request is invalid\n\nRecommended handling: Check headers and request format" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager context could not be resolved\n\nRecommended handling: Check API Manager credentials and environment" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/events/{eventId}": { "get": { "tags": [ "Events" ], "summary": "Get event", "description": "### Purpose\n\nRetrieve one specific open or close event by event ID in the selected customer context.\n\nAn event represents an open or close event of a car.\n\nUse this operation when the partner backend already knows the flinkey `eventId` and needs to retrieve the full event object.\n\nEvents are read-only records in normal partner workflows.\n\nThis operation does not create access rights.\n\nThis operation does not unlock or lock a vehicle.\n\nThis operation does not change assignments.\n\n### When to use this operation\n\nUse this operation when the partner backend needs one specific event record.\n\nTypical situations:\n\n- showing an event detail view,\n- checking a known event after retrieving an event list,\n- investigating support cases,\n- reconciling locally stored event data with the flinkey API,\n- validating whether a specific event still belongs to the selected customer context,\n- retrieving one event for audit or diagnostic purposes.\n\nFor list-based event history, use `GET /cars/{carId}/events`.\n\nFor a single known event ID, use this operation.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nEvents are operational records and should not be treated as the primary access permission model.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with one event object matching the event previously returned by the car event collection.\n- Collection-style OData options returned `400 Bad Request` with an OData error stating that the resource is not a collection.\n- The PROD error payload exposed internal exception and stack-trace details. Public documentation and partner logs must retain only the relevant status and message.\n\n### Async behavior\n\nSynchronous.\n\nThe result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nEvent data can contain operational access history.\n\nTreat event records as sensitive operational data.\n\nCar, user and event identifiers are environment-specific.\n\nDo not mix UAT and PROD IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "events.getEvent", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "eventId", "in": "path", "required": true, "description": "Database ID of the event", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Event was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Database ID of the event", "example": 12345 }, "dateTime": { "description": "Event date and time", "example": "2026-07-01T10:15:30.000" }, "utcDateTime": { "description": "Event date and time in UTC", "example": "2026-07-01T08:15:30.000Z" }, "userId": { "description": "Database ID of the user associated with the event", "example": 67890 }, "carId": { "description": "Database ID of the car associated with the event", "example": 123 }, "type": { "description": "Event type. Observed values include CarOpened, CarClosed and an empty string; clients must tolerate unknown or empty values", "example": "CarOpened" }, "userAgent": { "description": "User agent recorded for the event", "example": "partner-backend" }, "latitude": { "description": "Latitude of the event, if available", "example": 51.2562 }, "longitude": { "description": "Longitude of the event, if available", "example": 7.1508 } } }, "example": { "id": 12345, "dateTime": "2026-07-01T10:15:30.000", "utcDateTime": "2026-07-01T08:15:30.000Z", "userId": 67890, "carId": 123, "type": "CarOpened", "userAgent": "partner-backend", "latitude": 51.2562, "longitude": 7.1508 } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager was not found, or no event was found for the given eventId in the selected customer context\n\nRecommended handling: Check credentials, token context, Customer-ID, local event mapping and environment" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/cars/{carId}/events": { "get": { "tags": [ "Events" ], "summary": "Get events of a car", "description": "### Purpose\n\nRetrieve open and close events for one specific car in the selected customer context.\n\nAn event represents an open or close event of a car.\n\nUse this operation when the partner backend needs to read the event history of a car for operational visibility, audit views, support diagnostics or reconciliation.\n\nEvents are read-only records in normal partner workflows.\n\nThis operation does not create access rights.\n\nThis operation does not unlock or lock a vehicle.\n\nThis operation does not change assignments.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve car event history.\n\nTypical situations:\n\n- showing car open and close history in an operational backend,\n- investigating support cases,\n- reconciling expected car usage with recorded open and close events,\n- auditing access activity for a specific car,\n- retrieving event data for reporting,\n- checking whether an expected car open or close event was recorded.\n\nThe source documentation explicitly warns that returned data should always be limited using OData.\n\nFor production integrations, always use appropriate OData query options to limit result size.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nEvents are operational records and should not be treated as the primary access permission model.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with a direct JSON array.\n- `$top`, `$skip`, `$orderby=utcDateTime desc` and `$filter=type eq 'CarClosed'` were validated successfully.\n- Explicit ordering is required for deterministic pagination. Event IDs do not necessarily reflect chronological order.\n- The observed `type` values included `CarOpened`, `CarClosed` and an empty string. Partner implementations must handle unknown or empty values.\n- `dateTime` represented local wall-clock time but ended in `Z`; `utcDateTime` represented the corresponding UTC value. Use `utcDateTime` for ordering and time calculations.\n- `latitude` and `longitude` were returned as numbers in existing records and as `null` for the created validation event.\n\n### Async behavior\n\nSynchronous.\n\nThe result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nEvent data can contain operational access history.\n\nTreat event records as sensitive operational data.\n\nGroup, car, user and event identifiers are environment-specific.\n\nDo not mix UAT and PROD IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "events.getEventsOfCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Events of the car were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Database ID of the event" }, "dateTime": { "description": "Event date and time" }, "utcDateTime": { "description": "Event date and time in UTC" }, "userId": { "description": "Database ID of the user associated with the event" }, "carId": { "description": "Database ID of the car associated with the event" }, "type": { "description": "Event type. Observed values include CarOpened, CarClosed and an empty string; clients must tolerate unknown or empty values" }, "userAgent": { "description": "User agent recorded for the event" }, "latitude": { "description": "Latitude of the event, if available" }, "longitude": { "description": "Longitude of the event, if available" } } } }, "example": [ { "id": 12345, "dateTime": "2026-07-01T10:15:30.000", "utcDateTime": "2026-07-01T08:15:30.000Z", "userId": 67890, "carId": 123, "type": "CarOpened", "userAgent": "partner-backend", "latitude": 51.2562, "longitude": 7.1508 } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager was not found for the given OAuth ID claim data\n\nRecommended handling: Check credentials, token context and API Manager configuration" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/brands/{brand}/keys": { "get": { "tags": [ "Keyfob" ], "summary": "Get keys of brand", "description": "### Purpose\n\nRetrieve available keys for one specific vehicle brand for keyfob matching.\n\nThe keyfob area helps determine which key fits to a car.\n\nUse this operation after retrieving available brands with `Get brands`.\n\nThe response contains key and key form information that can be used for keyfob matching, setup and operational support workflows.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to retrieve key options for a selected vehicle brand.\n\nTypical situations:\n\n- continuing a keyfob selection workflow after brand selection,\n- supporting operational keybed or keyfob matching,\n- identifying available key forms for a vehicle brand,\n- retrieving box-related information for a key,\n- validating whether a selected brand has matching key data,\n- supporting vehicle setup or support workflows.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse keyfob operations for key matching, setup and support workflows.\n\n### Validation notes\n\n- The request succeeded with `200 OK` without a `Customer-ID` header.\n- `$top`, `$skip`, `$orderby=id desc` and the nested filter `$filter=keyForm/id eq {keyFormId}` were validated successfully.\n- Multiple result entries can share the same `keyForm` while representing different box, KPC, IXL, CAN or retrofit-set variants through `boxName` and `boxSapNumber`.\n- The top-level entry ID identifies a catalog combination and is not equivalent to `keyForm.id`.\n- CAN and IOX-Keybox catalog entries can be returned but are outside the standard BLE integration scope.\n- Treat `boxSapNumber` and `imageUrl` as opaque strings in normal partner integrations.\n\n### Async behavior\n\nSynchronous.\n\nThe key list is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "keyfob.getKeysOfBrand", "parameters": [ { "name": "Customer-ID", "in": "header", "required": false, "description": "Not required for this operation", "schema": { "type": "string" } }, { "name": "brand", "in": "path", "required": true, "description": "Vehicle brand name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Keys for the selected brand were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Key database ID" }, "brand": { "type": "string", "description": "Vehicle brand name" }, "boxName": { "type": [ "string", "null" ], "description": "Box name associated with the key" }, "boxSapNumber": { "type": [ "string", "null" ], "description": "Box SAP number associated with the key" }, "keyForm": { "type": "object", "description": "Key form information" }, "keyForm.id": { "type": "number", "description": "Key form database ID" }, "keyForm.name": { "type": "string", "description": "Key form name" }, "keyForm.imageUrl": { "type": "string", "description": "Image URL for the key form" } } } }, "example": [ { "id": "KEY-001", "brand": "Volkswagen", "boxName": "flinkey Box A1", "boxSapNumber": "SAP-BOX-001", "keyForm": { "id": "KF-001", "name": "Standard Key", "imageUrl": "https://example.com/keyform.png" } } ] } } }, "400": { "description": "Invalid brand was provided\n\nRecommended handling: Check the brand path parameter and use a brand returned by Get brands" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "The given brand could not be found\n\nRecommended handling: Check whether the brand exists and whether the brand value was encoded correctly in the URL" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/sdk/token": { "post": { "tags": [ "App SDK" ], "summary": "Get OAuth token", "description": "### Purpose\n\nRetrieve an OAuth ID token for SDK-based mobile access.\n\nThis operation is used by the partner backend to obtain an `id_token` for a specific flinkey user and customer context.\n\nThe returned `id_token` is used in the mobile SDK token exchange flow.\n\nThe partner mobile app must not call this operation directly with backend credentials.\n\nThe partner backend must request this token only after verifying that the current partner customer is allowed to access the requested vehicle.\n\n### When to use this operation\n\nUse this operation when the partner mobile app needs mobile access context for SDK-based local vehicle access.\n\nTypical situations:\n\n- preparing the Android app for local BLE access,\n- preparing the iOS app for local BLE access,\n- starting a Tapkey Mobile SDK login flow,\n- refreshing mobile access context,\n- enabling a customer-facing vehicle access flow in the partner app.\n\nBefore calling this operation, the partner backend should have resolved:\n\n- the correct `customerId`,\n- the correct `userId`,\n- the valid SDK Key from the flinkey Portal (UAT: https://portal-uat.flinkey.com | PROD: https://portal.flinkey.com),\n- the partner customer identity,\n- the partner vehicle access permission,\n- the assignment state required by the partner flow.\n\nDo not call this operation before backend access authorization has been checked.\n\nDo not expose backend credentials to the mobile app.\n\n### Validation notes\n\nPROD validation result:\n\n- `POST /sdk/token` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Content-Type: application/json`.\n- The `Customer-ID` header was not required; the customer context was provided through `customerId` in the request body.\n- The request body accepted `customerId`, `sdkKey` and `userId` as documented.\n- The operation returned `200 OK` with one JSON object containing `id_token`.\n- `id_token` was returned as a string.\n- The operation completed synchronously and did not produce a webhook result.\n- The returned token is sensitive and must remain redacted in documentation, logs, screenshots, tickets and AI prompts.\n\n### Async behavior\n\nSynchronous.\n\nThe OAuth ID token is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers,\n- `sdkKey`,\n- `id_token`.\n\nThe `id_token` is sensitive.\n\nDo not paste real tokens, SDK Keys or bearer tokens into documentation, examples, screenshots, tickets or AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.\n\nThe partner backend must validate partner-side access permission before returning mobile access context to the app.", "operationId": "appSdk.getOAuthToken", "parameters": [ { "name": "Customer-ID", "in": "header", "required": false, "description": "Customer context is provided in the request body", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth ID token was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id_token": { "type": "string", "description": "OAuth ID token used for the SDK token exchange flow", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example" } } }, "example": { "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.example" } } } }, "400": { "description": "Invalid combination of customerId, sdkKey and userId\n\nRecommended handling: Check SDK Key, customer context and user mapping" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "OAuth token could not be created or an internal server error occurred\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "number", "description": "Customer database ID", "example": 99001 }, "sdkKey": { "type": "string", "description": "SDK Key from the flinkey Portal", "example": "sk_uat_example_key_12345" }, "userId": { "type": "number", "description": "Database ID of the user", "example": 54321 } }, "required": [ "customerId", "sdkKey", "userId" ] }, "example": { "customerId": 99001, "sdkKey": "sk_uat_example_key_12345", "userId": 54321 } } } } } }, "/cars/{carId}/products": { "get": { "tags": [ "Cars" ], "summary": "Get products of car", "description": "### Validation notes\n\n- The base request returned `200 OK` with a direct product array.\n- `$top=0`, `$skip=1` and a non-matching `$filter` returned `200 OK` with an empty array, proving that those options are effective.\n- `$orderby` was accepted. Its visible sorting effect could not be observed with one returned product.\n- `$count=true` was accepted but returned neither an OData wrapper nor `@odata.count`.\n- A known car without assigned products returned `404 Not Found` with `\"No products are assigned to this car.\"`, not `200 OK` with an empty array.", "operationId": "cars.getProductsOfCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": 99001, "schema": { "type": "string" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Installed products returned as a direct JSON array", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123 }, "uniqueId": { "type": "string", "example": "PU-2024-00001" }, "serialNumber": { "type": "string", "example": "SN-100200300" }, "sapNumber": { "type": "string", "example": "SAP-400500" }, "dongleTerminationTimeStamp": { "type": "null", "example": null }, "type": { "type": "string", "example": "flinkey Box" }, "carId": { "type": "integer", "example": 456 } } } }, "example": [ { "id": 123, "uniqueId": "PU-2024-00001", "serialNumber": "SN-100200300", "sapNumber": "SAP-400500", "dongleTerminationTimeStamp": null, "type": "flinkey Box", "carId": 456 } ] } } }, "401": { "description": "Credentials or token are invalid" }, "404": { "description": "Customer context or car was not found, or the known car has no assigned products. The observed no-product response was \"No products are assigned to this car.\"" }, "500": { "description": "Server-side error" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/products/{productId}": { "get": { "tags": [ "Products" ], "summary": "Get product", "description": "### Purpose\n\nRetrieve one specific product by product ID in the selected customer context.\n\nA product represents a flinkey hardware product assigned to the customer context.\n\nIn standard developer integrations, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse this operation for operational lookup, reconciliation and support workflows where product-level information is required.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve one specific product.\n\nTypical situations:\n\n- validating a product reference,\n- checking product serial number,\n- checking product SAP number,\n- identifying product type,\n- troubleshooting vehicle or box setup,\n- reconciling hardware information with partner or support records.\n\nDo not treat `Product` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with one product object matching the product collection entry.\n- The response included the additional `carId` field.\n- `dongleTerminationTimeStamp` is a legacy response field from the former virtual Geotab dongle connection. That functionality is no longer supported; the field has no current integration meaning and must not drive business logic.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n\n### Async behavior\n\nSynchronous.\n\nThe product is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "products.getProduct", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Database ID of the product", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Product was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Product database ID", "example": 67890 }, "uniqueId": { "type": "string", "description": "Unique product identifier", "example": "PU-2024-00001" }, "serialNumber": { "type": "string", "description": "Product serial number", "example": "SN-100200300" }, "sapNumber": { "type": "string", "description": "SAP number", "example": "SAP-400500" }, "dongleTerminationTimeStamp": { "type": [ "string", "null" ], "description": "Functionally obsolete legacy field from the former virtual telematics-dongle connection; do not use for integration logic", "example": null }, "type": { "type": "string", "description": "Product type, for example flinkey Box or flinkey IQ", "example": "flinkey Box" }, "carId": { "type": [ "number", "null" ], "description": "Database ID of the assigned car, or null when no car is assigned", "example": 123 } } }, "example": { "id": 67890, "uniqueId": "PU-2024-00001", "serialNumber": "SN-100200300", "sapNumber": "SAP-400500", "dongleTerminationTimeStamp": null, "type": "flinkey Box", "carId": 123 } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or product was not found\n\nRecommended handling: Check credentials, Customer-ID and local productId reference" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/services/{serviceId}/products": { "get": { "tags": [ "Services" ], "summary": "Get product of service", "description": "### Purpose\n\nRetrieve the product assigned to one specific service in the selected customer context.\n\nA service represents the contract or service relationship associated with a flinkey product.\n\nA product represents a flinkey hardware product assigned to the customer context.\n\nUse this operation for operational lookup, reconciliation and support workflows where the relationship between a service and a product must be inspected.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve the product assigned to a specific service.\n\nTypical situations:\n\n- checking which product is assigned to a service,\n- validating service-to-product assignment,\n- retrieving product serial number from a known service reference,\n- retrieving product SAP number from a known service reference,\n- identifying product type,\n- supporting operational troubleshooting,\n- reconciling service and product state with partner or support records.\n\nFor standard access flows, the partner backend should usually work with `Car`, `User` and `Assignment`.\n\nUse this operation only where service-level or product-level lookup is required.\n\n### Validation notes\n\n- The base request returned `200 OK` with one product object despite the plural `/products` path.\n- The returned product ID matched the `productId` of the active service; the additional `carId` matched the prevalidated vehicle relation.\n- `dongleTerminationTimeStamp` remained present as a functionally obsolete legacy field with `null`.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n- When the service had no assigned product, the operation returned `404 Not Found` with `\"No product can be found that is assigned to this serviceId.\"`.\n\n### Async behavior\n\nSynchronous.\n\nThe product assigned to the service is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nService and product identifiers are environment-specific.\n\nDo not mix UAT and PROD service IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "services.getProductOfService", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "serviceId", "in": "path", "required": true, "description": "Database ID of the service", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Product assigned to the service was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Product database ID", "example": 67890 }, "uniqueId": { "type": "string", "description": "Unique product identifier", "example": "PU-2024-00001" }, "serialNumber": { "type": "string", "description": "Product serial number", "example": "SN-100200300" }, "sapNumber": { "type": "string", "description": "SAP number", "example": "SAP-400500" }, "dongleTerminationTimeStamp": { "type": [ "string", "null" ], "description": "Functionally obsolete legacy field from the former virtual telematics-dongle connection; do not use for integration logic", "example": null }, "type": { "type": "string", "description": "Product type, for example flinkey Box or flinkey IQ", "example": "flinkey Box" }, "carId": { "type": [ "number", "null" ], "description": "Database ID of the assigned car, or null when no car is assigned", "example": 123 } } }, "example": { "id": 67890, "uniqueId": "PU-2024-00001", "serialNumber": "SN-100200300", "sapNumber": "SAP-400500", "dongleTerminationTimeStamp": null, "type": "flinkey Box", "carId": 123 } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, service or assigned product was not found. The observed missing-relation response was \"No product can be found that is assigned to this serviceId.\"\n\nRecommended handling: Check credentials, Customer-ID, local serviceId reference and service-to-product assignment" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/products": { "get": { "tags": [ "Products" ], "summary": "Get products", "description": "### Purpose\n\nRetrieve products available in the selected customer context.\n\nA product represents a flinkey hardware product assigned to the customer context.\n\nIn standard developer integrations, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nUse product operations for operational lookup, reconciliation and support workflows where product-level information is required.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve or search products assigned to the selected customer context.\n\nTypical situations:\n\n- operational support,\n- hardware reconciliation,\n- checking which products are available for a customer,\n- identifying product serial numbers,\n- relating products to cars or services,\n- troubleshooting vehicle or box setup.\n\nDo not treat `Product` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with a direct JSON array.\n- `$top`, `$skip`, `$orderby=id desc` and `$filter=id eq {productId}` were validated successfully.\n- `serialNumber` and `sapNumber` are strings and may be empty; leading zeroes in serial numbers are significant.\n- The response included `carId` as a number or `null`.\n- `dongleTerminationTimeStamp` was `null` throughout the validated set and is a legacy artifact without current functionality.\n\n### Async behavior\n\nSynchronous.\n\nThe products are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "products.getProducts", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Products were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Product database ID" }, "uniqueId": { "type": "string", "description": "Unique product identifier" }, "serialNumber": { "type": "string", "description": "Product serial number" }, "sapNumber": { "type": "string", "description": "SAP number" }, "dongleTerminationTimeStamp": { "type": [ "string", "null" ], "description": "Functionally obsolete legacy field; do not use for integration logic" }, "type": { "type": "string", "description": "Product type, for example flinkey Box" }, "carId": { "type": [ "number", "null" ], "description": "Database ID of the assigned car, or null when no car is assigned" } } } }, "example": [ { "id": 67890, "uniqueId": "PU-2024-00001", "serialNumber": "SN-100200300", "sapNumber": "SAP-400500", "dongleTerminationTimeStamp": null, "type": "flinkey Box", "carId": 123 } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/services/{serviceId}": { "get": { "tags": [ "Services" ], "summary": "Get service", "description": "### Purpose\n\nRetrieve one specific service by service ID in the selected customer context.\n\nA service represents the contract or service relationship associated with a flinkey product.\n\nUse this operation for operational lookup, reconciliation and support workflows where service-level information is required.\n\nIn standard developer integrations, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve one specific service.\n\nTypical situations:\n\n- validating a service reference,\n- checking the assigned product ID,\n- checking whether a service is terminated,\n- retrieving service termination date,\n- retrieving service termination cause,\n- supporting operational troubleshooting,\n- reconciling service information with partner or support records.\n\nDo not treat `Service` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- Active and terminated service objects were retrieved successfully with `200 OK`.\n- `name` can be a string or `null`.\n- An active service returned a numeric `productId`, `isTerminated: false` and null termination fields.\n- A terminated service returned `productId: null`, `isTerminated: true`, a populated `terminationDate` and `terminationCause: ServiceIsNotNeededAnymore`.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n\n### Async behavior\n\nSynchronous.\n\nThe service is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nService and product identifiers are environment-specific.\n\nDo not mix UAT and PROD service IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "services.getService", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "serviceId", "in": "path", "required": true, "description": "Database ID of the service", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Service was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Service database ID", "example": 11111 }, "name": { "type": [ "string", "null" ], "description": "Service name, if available", "example": "flinkey Access" }, "productId": { "type": [ "number", "null" ], "description": "Product database ID assigned to the service", "example": 67890 }, "isTerminated": { "type": "boolean", "description": "Indicates whether the service is terminated", "example": false }, "terminationDate": { "type": [ "string", "null" ], "description": "Service termination date in date-time format, if available", "example": null }, "terminationCause": { "type": [ "string", "null" ], "description": "Termination cause, if available", "example": null } } }, "example": { "id": 11111, "name": "flinkey Access", "productId": 67890, "isTerminated": false, "terminationDate": null, "terminationCause": null } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or service was not found\n\nRecommended handling: Check credentials, Customer-ID and local serviceId reference" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/products/{productId}/services": { "get": { "tags": [ "Products" ], "summary": "Get service of product", "description": "### Purpose\n\nRetrieve service information assigned to one specific product in the selected customer context.\n\nA product represents a flinkey hardware product assigned to the customer context.\n\nA service represents the service relationship or service state associated with that product.\n\nUse this operation for operational lookup, reconciliation and support workflows where service-level information for a product is required.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve service information for a specific product.\n\nTypical situations:\n\n- checking whether a product has an assigned service,\n- checking whether the assigned service is terminated,\n- retrieving service termination date,\n- retrieving service termination cause,\n- supporting operational troubleshooting,\n- reconciling product and service state with partner or support records.\n\nDo not treat `Service` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with one service object despite the plural `/services` path.\n- The response included the additional `productId` field.\n- `name` was observed both as a string and as `null` across active services.\n- Development services with unlimited duration and ordinary automatically renewed services both returned `isTerminated: false` with null termination fields. Automatic renewal is handled outside the integration-facing service state.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n- When no service-to-product relation existed, the operation returned `404 Not Found` with `\"No product can be found for this productId that is assigned to this customerId.\"`. The wording is misleading and must not be interpreted as proof that the product itself was deleted.\n\n### Async behavior\n\nSynchronous.\n\nThe service information is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct and service identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs or service IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "products.getServiceOfProduct", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "productId", "in": "path", "required": true, "description": "Database ID of the product", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Service information for the product was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "Service database ID", "example": 11111 }, "name": { "type": [ "string", "null" ], "description": "Service name, if available", "example": "flinkey Access" }, "productId": { "type": [ "number", "null" ], "description": "Product database ID assigned to the service", "example": 123 }, "isTerminated": { "type": "boolean", "description": "Indicates whether the service is terminated", "example": false }, "terminationDate": { "type": [ "string", "null" ], "description": "Service termination date in date-time format, if available", "example": null }, "terminationCause": { "type": [ "string", "null" ], "description": "Termination cause, if available", "example": null } } }, "example": { "id": 11111, "name": "flinkey Access", "productId": 123, "isTerminated": false, "terminationDate": null, "terminationCause": null } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, product or assigned service data was not found. The observed missing-relation response was \"No product can be found for this productId that is assigned to this customerId.\"\n\nRecommended handling: Check credentials, Customer-ID, local productId reference and product assignment; verify the product separately before treating it as missing" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/services": { "get": { "tags": [ "Services" ], "summary": "Get services", "description": "### Purpose\n\nRetrieve services available in the selected customer context.\n\nA service represents the contract or service relationship associated with a flinkey product.\n\nUse this operation for operational lookup, reconciliation and support workflows where service-level information is required.\n\nIn standard developer integrations, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve or search services assigned to the selected customer context.\n\nTypical situations:\n\n- operational support,\n- contract or service reconciliation,\n- checking which services are available for a customer,\n- checking whether services are terminated,\n- retrieving service termination dates,\n- retrieving service termination causes,\n- relating services to products,\n- troubleshooting vehicle or box setup.\n\nDo not treat `Service` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The base request returned `200 OK` with a direct JSON array.\n- `$top`, `$skip`, `$orderby=id desc` and `$filter=isTerminated eq true` were validated successfully.\n- `name` can be a string or `null`.\n- Validated active services returned `isTerminated: false` with null termination fields.\n- Validated terminated services returned `isTerminated: true`, populated termination fields and `productId: null`.\n- `terminationDate` was returned without a timezone designator and with variable fractional-second precision. Do not interpret it as UTC without additional context.\n- `ServiceIsNotNeededAnymore` was the observed termination cause.\n\n### Async behavior\n\nSynchronous.\n\nThe services are returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nService and product identifiers are environment-specific.\n\nDo not mix UAT and PROD service IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "services.getServices", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Services were retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Service database ID" }, "name": { "type": [ "string", "null" ], "description": "Service name, if available" }, "productId": { "type": [ "number", "null" ], "description": "Product database ID assigned to the service" }, "isTerminated": { "type": "boolean", "description": "Indicates whether the service is terminated" }, "terminationDate": { "type": [ "string", "null" ], "description": "Service termination date in date-time format, if available" }, "terminationCause": { "type": [ "string", "null" ], "description": "Termination cause, if available" } } } }, "example": [ { "id": 11111, "name": "flinkey Access", "productId": 67890, "isTerminated": false, "terminationDate": null, "terminationCause": null } ] } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager or customer context was not found\n\nRecommended handling: Check credentials, token context and Customer-ID" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/services/{serviceId}/contracts": { "get": { "tags": [ "Contracts" ], "summary": "Get the contract of service", "description": "### Purpose\n\nRetrieve contract information assigned to one specific service in the selected customer context.\n\nA contract represents the contractual information associated with a flinkey service.\n\nUse this operation for operational lookup, reconciliation and support workflows where contract-level information for a service is required.\n\nIn standard developer integrations, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve contract information for a specific service.\n\nTypical situations:\n\n- retrieving contract metadata for operational support,\n- checking order number or document number,\n- checking contract start and end dates,\n- checking term of contract,\n- checking term of notice,\n- reconciling service and contract state with partner or support records,\n- troubleshooting service or product assignment.\n\nDo not treat `Contract` as the primary access permission object.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- The operation returned `200 OK` with one contract object despite the plural `/contracts` path.\n- Regular active and terminated services retained populated contract data. Service termination did not remove the historical contract object.\n- An unlimited service created directly in the administration portal returned the complete contract shape with every field set to `null`; missing SAP contract data did not produce `404 Not Found`.\n- Contract end dates and service termination are separate concepts. The contract object alone does not expose whether the service is terminated; use `isTerminated` from the service resource.\n- `unitOfNotice` was returned as an opaque string code and must not be interpreted without an explicit mapping.\n- Collection-style OData options returned `400 Bad Request` because the resource is not a collection.\n\n### Async behavior\n\nSynchronous.\n\nThe contract information is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nService and contract identifiers are environment-specific.\n\nDo not mix UAT and PROD service references or contract references.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "contracts.getContractOfService", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "serviceId", "in": "path", "required": true, "description": "Database ID of the service", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contract information for the service was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": [ "string", "null" ], "description": "Contract order number, if available", "example": "ORD-2026-0001" }, "documentNumber": { "type": [ "string", "null" ], "description": "Contract document number, if available", "example": "DOC-2026-0001" }, "orderPosition": { "type": [ "number", "null" ], "description": "Contract order position", "example": "1" }, "start": { "type": [ "string", "null" ], "description": "Contract start date in date-time format, if available", "example": "2026-01-31T10:00:00Z" }, "end": { "type": [ "string", "null" ], "description": "Contract end date in date-time format, if available", "example": "2027-01-31T10:00:00Z" }, "termOfContract": { "type": [ "number", "null" ], "description": "Term of contract", "example": 12 }, "termOfNotice": { "type": [ "number", "null" ], "description": "Term of notice", "example": 3 }, "unitOfNotice": { "type": [ "string", "null" ], "description": "Unit of notice", "example": "months" } } }, "example": { "orderNumber": "ORD-2026-0001", "documentNumber": "DOC-2026-0001", "orderPosition": "1", "start": "2026-01-31T10:00:00Z", "end": "2027-01-31T10:00:00Z", "termOfContract": 12, "termOfNotice": 3, "unitOfNotice": "months" } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or service was not found\n\nRecommended handling: Check credentials, Customer-ID and local serviceId reference" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/oauth2/token": { "post": { "tags": [ "Authentication" ], "summary": "Get token", "description": "### Purpose\n\nRetrieve an OAuth access token for protected flinkey API v3 requests.\n\nThe returned access token is used by the partner backend as bearer token when calling protected API operations.\n\nThis operation is part of backend authentication.\n\nIt must not be called from mobile apps, frontend applications or browser JavaScript.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to authenticate against the flinkey API.\n\nTypical situations:\n\n- backend startup,\n- first protected API request,\n- access token expired,\n- access token missing from backend cache,\n- retry after receiving an authentication-related response from a protected API call.\n\n### Validation notes\n\nPROD validation result:\n\n- `POST /oauth2/token` with API Manager username, API Manager password and `grant_type=password` returned `200 OK`.\n- The response contained `access_token`, `token_type` and `expires_in`.\n- The UAT validation must confirm the actual wire type of `expires_in`; clients should safely accept a positive number or numeric string.\n- The returned access token was used successfully as bearer token for the subsequently validated protected API operations.\n- The request did not require an `Authorization` header or `Customer-ID` header.\n- This validation was completed before the endpoint-level validation status model was introduced and was reconciled retrospectively in document version 0.15.\n\n### Async behavior\n\nSynchronous.\n\nThe token is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- API Manager username,\n- API Manager password,\n- access token,\n- full request body,\n- full response body if it contains the token.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.", "operationId": "authentication.getToken", "parameters": [ { "name": "Customer-ID", "in": "header", "required": false, "description": "Customer context is not required for token retrieval", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Access token was created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token used as bearer token for protected API v3 requests", "example": "eyJhbGciOiJSUzI1NiJ9.access_token_example" }, "expires_in": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" } ], "description": "Token lifetime in seconds; clients should normalize either representation to a positive integer", "example": 3600 }, "token_type": { "type": "string", "description": "Token type returned by the authentication endpoint", "example": "Bearer" } } }, "example": { "access_token": "eyJhbGciOiJSUzI1NiJ9.access_token_example", "expires_in": 3600, "token_type": "Bearer" } } } }, "401": { "description": "Invalid or missing API subscription key / API key\n\nRecommended handling: Check flinkey-API-Key and environment configuration" }, "415": { "description": "Wrong Content-Type\n\nRecommended handling: Send request as application/x-www-form-urlencoded" } }, "security": [ { "apiKey": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "API Manager username", "example": "api-manager@example.com" }, "password": { "type": "string", "description": "API Manager password", "example": "your-password" }, "grant_type": { "type": "string", "description": "Must be password", "example": "password" } }, "required": [ "username", "password", "grant_type" ] }, "example": { "username": "api-manager@example.com", "password": "your-password", "grant_type": "password" } } } } } }, "/users/{userId}": { "get": { "tags": [ "Users" ], "summary": "Get user", "description": "### Purpose\n\nRetrieve one specific user by user ID in the selected customer context.\n\nA user represents the access identity that can receive assignments for cars.\n\nFor standard full partner integrations, the partner backend usually works with anonymous flinkey users.\n\nUse this operation to validate or inspect an existing user mapping.\n\n### When to use this operation\n\nUse this operation when the partner backend needs to retrieve one specific flinkey user.\n\nTypical situations:\n\n- validating a local user mapping,\n- checking whether a mapped user still exists,\n- troubleshooting assignment creation,\n- reconciling partner customer or driver records with flinkey user records,\n- inspecting user data before using the user in an assignment flow.\n\nIn most integrations, the partner backend should persist a mapping between the partner customer or driver and the flinkey `userId`.\n\nUse the mapped `userId` to retrieve the correct flinkey user.\n\nDo not create a new user when an existing mapped user should be used.\n\n### Validation notes\n\nPROD validation result:\n\n- `GET /users/{userId}` was successfully executed with `flinkey-API-Key`, `Authorization: Bearer {{accessToken}}` and `Customer-ID`.\n- The response is a single user object.\n- `id` is returned as number.\n- `emailAddress` is returned as string.\n- `userData` is returned as an object containing `firstName` and `lastName`.\n- Concrete names and e-mail addresses from validation must not be copied into public documentation, examples, screenshots or AI prompts.\n- OData collection query options such as `$filter`, `$orderby`, `$count`, `$skip` and `$top` are not supported because this endpoint returns a single resource, not a collection.\n- `$select` was tested and resulted in a timeout. The flinkey API does not support `$select`; do not use it on this or any other endpoint.\n- Use `GET /users` for OData-based filtering, ordering, paging or collection query behavior.\n\n### Async behavior\n\nSynchronous.\n\nThe user is returned directly in the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nUser identifiers are environment-specific.\n\nDo not mix UAT and PROD user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "users.getUser", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "userId", "in": "path", "required": true, "description": "Database ID of the user", "schema": { "type": "number" } } ], "responses": { "200": { "description": "User was retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number", "description": "User database ID", "example": 123 }, "emailAddress": { "type": "string", "description": "E-mail address of the user", "example": "user@example.com" }, "userData": { "type": "object", "description": "User profile data", "example": { "firstName": "Max", "lastName": "Mustermann" } }, "userData.firstName": { "type": [ "string", "null" ], "description": "First name" }, "userData.lastName": { "type": [ "string", "null" ], "description": "Last name" } } }, "example": { "id": 123, "emailAddress": "user@example.com", "userData": { "firstName": "Max", "lastName": "Mustermann" } } } } }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or user was not found\n\nRecommended handling: Check credentials, Customer-ID and local userId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Core", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/installations": { "put": { "tags": [ "Installations" ], "summary": "Install product into car", "description": "### Purpose\n\nInstall a product into a car in the selected customer context.\n\nA product represents a flinkey hardware product.\n\nA car is the API abstraction used for vehicle-related access flows.\n\nThis operation links a product to a car.\n\nUse this operation for operational setup workflows where a flinkey product must be assigned to a vehicle record.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to install a product into a car.\n\nTypical situations:\n\n- assigning a flinkey product to a car,\n- completing vehicle setup,\n- linking a physical product to a vehicle record,\n- preparing a car for assignment-based access flows,\n- correcting product-to-car setup after reconciliation,\n- operational support or installation workflows.\n\nBefore calling this operation, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `carId`,\n- the product identifier,\n- whether the product already has an assigned service,\n- whether another product of the same type is already installed in the car.\n\nThe public API catalog does not expose an operation for creating the required service-to-product or service-to-Box relation.\n\nIn the validated UAT operating model, this relation was established by the responsible sales or administrative process before installation. Treat it as an external operational prerequisite and verify it through the product and service lookup operations before calling `PUT /installations`.\n\nIf the relation is missing, the installation can return `409 Conflict`; do not retry the write automatically without first reconciling the product and service state.\n\nFor standard access flows, assignments are created between `User` and `Car`.\n\nProduct installation is an operational setup step and should not be treated as an access permission.\n\n### Validation notes\n\n- The controlled PROD request returned `204 No Content` with an empty response body.\n- The product-to-car relation was immediately visible through `Get products of car`.\n- `Get product` returned the same product with the target `carId`.\n- Product identity fields remained unchanged.\n- The resulting installation was also confirmed in the Admin Portal.\n\n### Async behavior\n\nSynchronous.\n\nThe installation result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct and car identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs, serial numbers, unique IDs or car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "installations.installProductIntoCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Product was installed into the car successfully" }, "400": { "description": "Invalid carId or no valid product identifier was provided\n\nRecommended handling: Check carId, productId, serialNumber and uniqueId" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, car or product was not found\n\nRecommended handling: Check credentials, Customer-ID, car assignment and product identifier" }, "409": { "description": "Product cannot be installed because of current product, service or car state\n\nRecommended handling: Check whether the product is already installed, has no service assigned or another product of the same type is already installed in the car" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carId": { "type": "number", "description": "Database ID of the car", "example": 12345 }, "productId": { "type": [ "number", "null" ], "description": "Database ID of the product", "example": 67890 }, "serialNumber": { "type": [ "string", "null" ], "description": "Product serial number", "example": null }, "uniqueId": { "type": [ "string", "null" ], "description": "Unique product identifier", "example": null } }, "required": [ "carId" ] }, "example": { "carId": 12345, "productId": 67890, "serialNumber": null, "uniqueId": null } } } } }, "delete": { "tags": [ "Installations" ], "summary": "Uninstall product from car", "description": "### Purpose\n\nUninstall a product from a car in the selected customer context.\n\nA product represents a flinkey hardware product.\n\nA car is the API abstraction used for vehicle-related access flows.\n\nThis operation removes the link between a product and a car.\n\nUse this operation for operational setup, replacement, correction or support workflows where an installed product must be removed from a vehicle record.\n\nIf a flinkey Box is uninstalled, assignments of the car are also removed.\n\nThe assignment deletion operations are processed asynchronously and their results are delivered through webhook.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to uninstall a product from a car.\n\nTypical situations:\n\n- removing a flinkey product from a car,\n- replacing hardware,\n- correcting product-to-car setup after reconciliation,\n- preparing a product for reassignment,\n- cleaning up an incorrect installation,\n- operational support or workshop workflows.\n\nBefore calling this operation, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `carId`,\n- the product identifier,\n- whether the product is currently assigned to the given car,\n- whether active assignments exist for the car,\n- whether assignment deletion side effects are acceptable for the current workflow.\n\nFor standard access flows, assignments are created between `User` and `Car`.\n\nProduct uninstallation is an operational setup step and should not be treated as an access permission update only.\n\n### Validation notes\n\n- The controlled PROD request returned `204 No Content` with an empty response body.\n- Removal was confirmed in the Admin Portal.\n- `Get products of car` subsequently returned `404 Not Found` with `\"No products are assigned to this car.\"`.\n- `Get product` still returned the unchanged product, now with `carId: null`.\n- Existing assignments were not treated as a blocker in the controlled test client. Assignment removal remains a documented possible asynchronous side effect and must be observed in partner workflows where assignment state matters.\n\n### Async behavior\n\nPartly asynchronous.\n\nThe product uninstallation request returns `204 NO CONTENT` when the uninstallation operation was accepted or completed successfully.\n\nIf a flinkey Box is uninstalled, assignments of the car are also removed.\n\nThose assignment deletion operations are asynchronous.\n\nThe partner backend must process the related assignment deletion webhook results before treating assignment state as final.\n\n### Webhook result\n\nYes.\n\nThis operation can produce assignment deletion result webhooks when assignments of the car are removed as part of uninstalling a flinkey Box.\n\nThe product uninstallation itself is represented by the API response.\n\nThe related assignment deletion results are represented by webhook events.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nProduct, car and assignment identifiers are environment-specific.\n\nDo not mix UAT and PROD product IDs, serial numbers, unique IDs, car IDs or assignment IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "installations.uninstallProductFromCar", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Product was uninstalled from the car successfully" }, "400": { "description": "Invalid carId or no valid product identifier was provided\n\nRecommended handling: Check carId, productId, serialNumber and uniqueId" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, car or product was not found\n\nRecommended handling: Check credentials, Customer-ID, car assignment and product identifier" }, "409": { "description": "Product cannot be uninstalled because of current installation state\n\nRecommended handling: Check whether the product is already uninstalled or whether the product is not assigned to the given car" }, "415": { "description": "Request content type is missing or incorrect\n\nRecommended handling: Ensure Content-Type: application/json is used" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carId": { "type": "number", "description": "Database ID of the car", "example": 12345 }, "productId": { "type": [ "number", "null" ], "description": "Database ID of the product", "example": 67890 }, "serialNumber": { "type": [ "string", "null" ], "description": "Product serial number", "example": null }, "uniqueId": { "type": [ "string", "null" ], "description": "Unique product identifier", "example": null } }, "required": [ "carId" ] }, "example": { "carId": 12345, "productId": 67890, "serialNumber": null, "uniqueId": null } } } } } }, "/groups/{groupId}/cars/{carId}": { "delete": { "tags": [ "Grouping" ], "summary": "Remove car from group", "description": "### Purpose\n\nRemove one specific car from one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a car must be removed from an existing group.\n\nThis operation changes group membership only.\n\nIt does not delete the car.\n\nIt does not remove assignments.\n\nIt does not revoke vehicle access rights.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to remove a car from a group.\n\nTypical situations:\n\n- removing a car from an operational group,\n- correcting group membership after reconciliation,\n- cleaning up group membership after fleet-side changes,\n- maintaining group-based operational views,\n- removing a car from a support or setup group,\n- preparing a group for deletion.\n\nBefore removing a car from a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `carId`,\n- whether the group exists,\n- whether the car exists,\n- whether the car is currently assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned an empty car array.\n\n### Async behavior\n\nSynchronous.\n\nThe removal result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\nRemoving a car from a group does not trigger assignment lifecycle webhooks.\n\nIf vehicle access must be changed, use the appropriate assignment operation.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and car identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or car IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.removeCarFromGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } }, { "name": "carId", "in": "path", "required": true, "description": "Database ID of the car", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Car was removed from the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group, car or group membership was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping, local carId mapping and current group membership" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/groups/{groupId}/products/{productId}": { "delete": { "tags": [ "Grouping" ], "summary": "Remove product from group", "description": "### Purpose\n\nRemove one specific product from one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a product must be removed from an existing group.\n\nThis operation changes group membership only.\n\nIt does not delete the product.\n\nIt does not unlink a service from a product.\n\nIt does not uninstall a product from a car.\n\nIt does not remove assignments.\n\nIt does not revoke vehicle access rights.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to remove a product from a group.\n\nTypical situations:\n\n- removing a product from an operational group,\n- correcting group membership after reconciliation,\n- cleaning up group membership after product-side changes,\n- maintaining group-based operational views,\n- removing a product from a support or setup group,\n- preparing a group for deletion.\n\nBefore removing a product from a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `productId`,\n- whether the group exists,\n- whether the product exists,\n- whether the product is currently assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned an empty product array.\n\n### Async behavior\n\nSynchronous.\n\nThe removal result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\nRemoving a product from a group does not trigger assignment lifecycle webhooks.\n\nIf vehicle access must be changed, use the appropriate assignment operation.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and product identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or product IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.removeProductFromGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } }, { "name": "productId", "in": "path", "required": true, "description": "Database ID of the product", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Product was removed from the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context or group was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping and local productId mapping" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/groups/{groupId}/services/{serviceId}": { "delete": { "tags": [ "Grouping" ], "summary": "Remove service from group", "description": "### Purpose\n\nRemove one specific service from one specific group. This changes group membership only; it does not terminate the service, unlink it from a product or change vehicle access assignments.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty response body.\n- A subsequent `GET /groups/{groupId}/services` returned `200 OK` with an empty array.\n- The test group was later deleted after all remaining relations had been removed.\n\n### Async behavior\n\nSynchronous. No webhook is produced.\n\n### Security notes\n\nNever log the API key, bearer token or full request headers. Group and service IDs are environment-specific.", "operationId": "grouping.removeServiceFromGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } }, { "name": "serviceId", "in": "path", "required": true, "description": "Database ID of the service", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "Service membership was removed successfully" }, "401": { "description": "Credentials or token are invalid\n\nRecommended handling: Check API key, bearer token and environment" }, "404": { "description": "Customer context, group, service or membership was not found\n\nRecommended handling: Reconcile group membership and identifiers before retrying" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } }, "/groups/{groupId}/users/{userId}": { "delete": { "tags": [ "Grouping" ], "summary": "Remove user from group", "description": "### Purpose\n\nRemove one specific user from one specific group in the selected customer context.\n\nA group is an entity represented by a group ID.\n\nA group can contain cars, users, services and products.\n\nUse this operation for operational grouping workflows where a user must be removed from an existing group.\n\nThis operation changes group membership only.\n\nIt does not delete the user.\n\nIt does not remove assignments.\n\nIt does not revoke vehicle access rights.\n\n### When to use this operation\n\nUse this operation when the partner backend or operational backend needs to remove a user from a group.\n\nTypical situations:\n\n- removing a user from an operational group,\n- correcting group membership after reconciliation,\n- cleaning up group membership after customer-side changes,\n- maintaining group-based operational views,\n- removing a user from a support or setup group,\n- preparing a group for deletion.\n\nBefore removing a user from a group, the partner backend should have resolved:\n\n- the correct `Customer-ID`,\n- the flinkey `groupId`,\n- the flinkey `userId`,\n- whether the group exists,\n- whether the user exists,\n- whether the user is currently assigned to the group.\n\nFor standard access flows, partner backends usually work primarily with `Car`, `User` and `Assignment`.\n\nGroup membership is an operational grouping concept and should not be treated as the primary vehicle access permission.\n\nAccess permissions are managed through assignments between `User` and `Car`.\n\n### Validation notes\n\n- PROD returned `204 No Content` with an empty body. A control GET returned an empty user array.\n\n### Async behavior\n\nSynchronous.\n\nThe removal result is represented by the API response.\n\n### Webhook result\n\nNo.\n\nThis operation does not produce a webhook result.\n\nRemoving a user from a group does not trigger assignment lifecycle webhooks.\n\nIf vehicle access must be removed, use the appropriate assignment operation.\n\n### Security notes\n\nNever log:\n\n- `flinkey-API-Key`,\n- bearer token,\n- full request headers.\n\nGroup and user identifiers are environment-specific.\n\nDo not mix UAT and PROD group IDs or user IDs.\n\nUse placeholders in documentation, examples, screenshots and AI prompts.\n\nFor standard partner integrations, the mobile app must not receive API Manager credentials, backend bearer tokens or the `flinkey-API-Key`.", "operationId": "grouping.removeUserFromGroup", "parameters": [ { "name": "Customer-ID", "in": "header", "required": true, "description": "Customer database ID", "schema": { "type": "string" } }, { "name": "groupId", "in": "path", "required": true, "description": "Database ID of the group", "schema": { "type": "integer" } }, { "name": "userId", "in": "path", "required": true, "description": "Database ID of the user", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "User was removed from the group successfully" }, "401": { "description": "Invalid subscription key or missing / invalid access token\n\nRecommended handling: Check flinkey-API-Key, bearer token and environment configuration" }, "404": { "description": "API Manager, customer context, group, user or group membership was not found\n\nRecommended handling: Check credentials, token context, Customer-ID, local groupId mapping, local userId mapping and current group membership" }, "500": { "description": "Server-side error\n\nRecommended handling: Retry later if appropriate and escalate if persistent" } }, "security": [ { "apiKey": [], "bearerAuth": [] } ], "x-flinkey-integration-priority": "Operational", "x-flinkey-validation-status": "PROD validated", "x-flinkey-agent-ready": "Yes" } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "flinkey-API-Key", "description": "Partner-specific API key from the flinkey Portal.\n\n- UAT: https://portal-uat.flinkey.com\n- PROD: https://portal.flinkey.com" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "access token", "description": "Access token returned by POST /oauth2/token." } } }, "x-flinkey-source": { "documentVersion": "0.20", "lastEdited": "2026-07-23", "sha256": "ce9837aec279e0afb0017cde4efe2f2de5cf3da23506427484b9d2b4c7794b61", "generatedOperationCount": 54, "generatedHttpOperationCount": 51, "generatedWebhookCount": 3 } }