---
title: "Lock or unlock"
method: POST
path: "/lkbx/session/current"
tags: ["Lock Sessions"]
---

# Lock or unlock

`POST /lkbx/session/current`

## Request

- Base URL: `https://dashboard.researchanddesire.com/api/v1`
- URL: `https://dashboard.researchanddesire.com/api/v1/lkbx/session/current`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Token URL: `/oauth/token` scopes: `lkbx:control`

Start a new lock session or complete (unlock) the active session. User IDs (target and keyholders) are validated against your accessible users before the action is performed. When starting a partner's lock, the authenticated user is automatically assigned as a keyholder, including when keyholderIds is omitted or empty. OAuth partner starts require lkbx:keyholders. A definitive Chaster creation rejection cancels the local session before returning an error. If Chaster's outcome is uncertain, the response is 201 with the created lockSessionId and a warning; inspect the current session and do not retry creation blindly.

## Request body

- LockUnlockRequest
  - `action` 'lock' | 'unlock', required: Action to perform
  - `lockSettingsId` integer: Lock template ID (for lock action). Fixed templates use duration in seconds. Only templates with isRandomDuration=true use minDuration/maxDuration; equal bounds select that exact duration.
  - `keyholderIds` integer[]: User IDs to assign as keyholders (for lock action). All IDs must be users you have access to. The initiating user is always included for partner locks. Assignments require lkbx:keyholders for OAuth clients.
  - `targetUserId` integer: User to lock/unlock (defaults to authenticated user). Must be a user you have access to.
  - `isTestLock` boolean: Override test lock setting from template. When true, the lock owner can unlock without a keyholder. Only used with lock action.

## Response `200`

Lock session completed

- UnlockSuccessResponse
  - `ok` true, required
  - `data` object, required
    - `message` string, required

## Other responses

- `201`: Lock session created
- `400`: Invalid request or operation failed
- `401`: Authentication required or token invalid
- `403`: Inaccessible user ID
- `404`: User not found

## Changes

- **2026-09-22** `4d10cc21b424`: 1 info
  - added the optional property `data/warning` to the response with the `201` status
- **2026-09-22** `2411203b3c10`: 2 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - the endpoint scheme security `oauth2` was added to the API

[Operation history](https://skmtc.dev/researchanddesire/apis/research-and-desire-api/changes/lkbx/session/current/post.md)

---

[API](https://skmtc.dev/researchanddesire/apis/research-and-desire-api.md) - [All operations](https://skmtc.dev/researchanddesire/apis/research-and-desire-api/llms.txt) - [OpenAPI document](https://skmtc.dev/researchanddesire/apis/research-and-desire-api/revisions/682fc4d7f6d5?raw)