--- updatedAt: 2026-05-27T11:17:14.000Z agentTools: projectIndex: https://developer.unloc.app/llms.txt --- # Create a new Danalock Lock Connection Sets up a new Danalock Lock Connection. Note: - The `username` and `password` must match the ones used to create the [Danalock Vendor Account](https://api.danalock.com/account/create). - If there is already a Lock Connection with the specified `username` in **any other state than** `error` or `disconnected`, the request will fail. - A Danalock Account **may only be linked to a single Lock Connection** within the Unloc platform. | | | | --- | --- | | Required Scope | `project.admin`,`project.installer` | # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Unloc API", "version": "2.0", "description": "The Unloc API allows you to fully manage your Organizations and the belonging Projects.\n\nGetting started:\n\n1. Contact us to make an Organization and API Credentials for you. Make sure to not lose the client id/secret.\n2. Exchange your secret for a JWT using the [OAuth2 Token](https://developer.unloc.app/reference/gettoken) endpoint.\n3. Create a Project to be managed by the Organization.\n4. Create a Lock Connection for the Project.\n5. Create Keys for your Users.\n\nAll the API endpoints in the Unloc API require a bearer token to be present in the authorization header, with the format authorization: \"Bearer [JWT]\".\n", "contact": { "name": "Jan Erik", "email": "janerik@unloc.app" } }, "servers": [ { "url": "https://api.unloc.app", "description": "Production server." } ], "tags": [ { "name": "Lock Connections", "description": "Lock Connection endpoints are used to get, and update Lock Connections in this Project." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "paths": { "/v2/projects/{projectId}/lock-connections/danalock": { "post": { "summary": "Create a new Danalock Lock Connection", "description": "Sets up a new Danalock Lock Connection.\n\nNote:\n- The `username` and `password` must match the ones used to create the [Danalock Vendor Account](https://api.danalock.com/account/create).\n- If there is already a Lock Connection with the specified `username` in **any other state than** `error` or `disconnected`, the request will fail. \n- A Danalock Account **may only be linked to a single Lock Connection** within the Unloc platform.\n\n| | |\n| --- | --- |\n| Required Scope | `project.admin`,`project.installer` |\n", "operationId": "createDanalockLockConnection", "security": [ { "BearerAuth": [ "project.admin", "project.installer" ] } ], "tags": [ "Lock Connections" ], "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string", "format": "uuid v4" }, "example": "d45031c2-be07-4d20-adbe-4e51e6ad0fed", "description": "ID of the Project. Must match the one in the JWT." } ], "requestBody": { "description": "Input containing the Danalock Lock Connection details.", "required": true, "content": { "application/json": { "schema": { "description": "Data to create Lock Connection with.", "properties": { "username": { "type": "string", "description": "Danalock account email address.", "example": "george@example.com" }, "password": { "type": "string", "description": "Danalock account password.", "example": "Passw0rd123" } }, "required": [ "username", "password" ] } } } }, "responses": { "200": { "description": "The newly created Danalock Lock Connection", "content": { "application/json": { "schema": { "description": "A Lock Connection.", "properties": { "lockConnection": { "allOf": [ { "description": "A Lock Connection is an entity that represents a link between a Project and a Lock vendor, e.g. Danalock. Lock Connections are used to perform operations on your behalf, such as fetching your Locks and making Keys.", "type": "object", "properties": { "id": { "type": "string", "format": "uuid v4", "example": "8e217374-d1ff-43b1-9a99-540ea5645b30", "description": "ID of this Lock Connection." }, "state": { "type": "string", "enum": [ "connecting", "connected", "refreshing", "disconnected", "error" ], "description": "Available values are:\n - `connecting`: Lock Connection has been created and our system is currently setting up required data. This should not take more than a few seconds, depending on the number of locks\n - `connected`: Lock Connection is fully established.\n - `refreshing`: The system is currently in the process of refreshing the locks of this Lock Connection.\n - `disconnected`: This Lock Connection is no longer active.\n - `error`: There is something wrong with this Lock Connection.\n", "example": "connecting" }, "lastSuccessfullyRefreshed": { "type": "string", "format": "date-time", "example": "2021-05-12T11:54:09.158Z", "description": "The date at which we last successfully refreshed this Lock Connection." }, "accountId": { "type": "string", "example": "user@lock-vendor.com", "description": "Typically username or account id in the vendor system" }, "accountDisplayName": { "type": "string", "example": "user@lock-vendor.com", "description": "The display name of the vendor account, usually the same as `accountId`." }, "created": { "type": "string", "format": "date-time", "example": "2020-05-12T11:54:09.158Z", "description": "Date for when this Lock Connection was created." }, "metadata": { "description": "Additional custom data linked to this entity presented in a _key–value_ pairs format. Use this to store additional data that is not part of the core data model.\nUp to 20 _key–value_ pairs are supported. Each _key_'s length can be up to 40 characters long, and each _value_'s maximum length is 256.\nMetadata Keys with the prefix `unloc` is reserved, and can be overwritten by the system.", "type": "object", "additionalProperties": { "type": "string", "description": "A custom field for you to store additional data." }, "example": { "groupId": "abc_123" } } } }, { "type": "object", "properties": { "vendor": { "type": "string", "example": "danalock", "description": "The name of the vendor." } } } ] } } } } } }, "400": { "description": "Request has missing or invalid parameters.", "content": { "application/json": { "schema": { "description": "Request has missing or invalid parameters.", "properties": { "type": { "type": "string", "description": "URI to the documentation for the error." }, "title": { "type": "string", "description": "Human-readable summary of the error." }, "detail": { "type": "string", "description": "Human-readable explanation specific to this occurrence of the problem." }, "status": { "type": "integer", "example": 400, "description": "HTTP status code for the error." }, "traceContext": { "type": "string", "description": "A unique identifier for this error occurrence." }, "invalidParams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the invalid parameter.", "example": "lockId" }, "reason": { "type": "string", "description": "The reason why the parameter is invalid.", "example": "must have required property 'lockId'" } } } } } } } } }, "401": { "description": "Unauthorized request. JWT invalid or expired.", "content": { "application/json": { "schema": { "description": "Unauthorized request. JWT invalid or expired.", "properties": { "error": { "type": "string", "description": "Short identifier for the error.", "example": "JsonWebTokenError" }, "errorDescription": { "type": "string", "description": "Verbose description of the error meant for human consumption.", "example": "JWT expired" } } } } } } } } } } } ```