Setup

POST /v2/setup

Resolves or creates the partner, client, and partner user entities for the authenticated LM user. All three operations run inside a single database transaction. The endpoint is idempotent — repeated calls return the same entities without creating duplicates.

This endpoint does not follow the standard client-scoped resource pattern because it bootstraps the client itself. It is the entry point for LM-authenticated users whose organizations may not yet exist in the system.

For general endpoint design conventions, see the Design Guidelines.

When to use this endpoint

Scenario	Why this endpoint
First LM user login	Creates partner, client, and partner user in one call
Subsequent LM user login	Returns existing entities without side effects
Frontend needs to resolve LM claims to internal IDs	Maps accountId → partner, clientId → client, userId → partner user

Authentication

Requires an LM bearer token. The entity resolution is driven entirely by the token claims — there is no request body.

Claim	Maps to
accountId	Partner (lm_partner_id)
clientId	Client (lm_client_id)
userId	Partner user (lm_user_id)
userEmail	Partner user email

Requests authenticated with a Cognito token or missing LM claims are rejected with 403.

Response

Returns a SetupResponse object with status 200 OK.

The created boolean on each entity indicates whether it was created by this call (true) or already existed (false).

Example Request

curl -X POST "https://api.example.com/v2/setup" \
  -H "Authorization: Bearer YOUR_LM_TOKEN"

Example Responses

First call — all entities created

{
  "partner": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lm_partner_id": "4cjbb",
    "name": "4cjbb",
    "created": true
  },
  "client": {
    "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
    "lm_client_id": "Z6RWR",
    "name": "Z6RWR",
    "created": true
  },
  "partner_user": {
    "id": "c9d0e1f2-a3b4-5678-90ab-cdef12345678",
    "lm_user_id": "m5ktu",
    "email": "liam+demo@example.com",
    "created": true
  }
}

Subsequent call — all entities already exist

{
  "partner": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lm_partner_id": "4cjbb",
    "name": "4cjbb",
    "created": false
  },
  "client": {
    "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
    "lm_client_id": "Z6RWR",
    "name": "Z6RWR",
    "created": false
  },
  "partner_user": {
    "id": "c9d0e1f2-a3b4-5678-90ab-cdef12345678",
    "lm_user_id": "m5ktu",
    "email": "liam+demo@example.com",
    "created": false
  }
}

Error Responses

Status	Description
401	Authentication required
403	Endpoint requires an LM bearer token
409	Entity ownership conflict (client or user belongs to a different partner)
500	Server error

403 — non-LM token

{
  "error": {
    "code": "lm_token_required",
    "message": "This endpoint requires an LM bearer token.",
    "details": null
  }
}

409 — client belongs to a different partner

Returned when the LM clientId resolves to an existing client that is already associated with a different partner than the one resolved from accountId.

{
  "error": {
    "code": "client_partner_mismatch",
    "message": "The requested client is already associated with a different partner.",
    "details": null
  }
}

409 — user belongs to a different partner

Returned when the LM userId resolves to an existing partner user that is already associated with a different partner than the one resolved from accountId.

{
  "error": {
    "code": "user_partner_mismatch",
    "message": "The requested user is already associated with a different partner.",
    "details": null
  }
}

Design Notes

• Not client-scoped. Unlike other v2 endpoints, setup is at the root (/v2/setup) because it creates the client entity itself.
• No request body. All inputs are derived from the LM bearer token claims.
• Always 200. The endpoint returns 200 OK regardless of whether entities were created or already existed. The created boolean on each entity communicates what happened.
• Transactional. All three ensure-or-create operations run in a single database transaction. If any step fails, no entities are created.

Data Transfer Objects (DTOs)

SetupPartner

Partner entity resolved or created during setup.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "lm_partner_id": "4cjbb",
  "name": "4cjbb",
  "created": true
}

Field	Type	Nullable	Description
id	string (uuid)	No	Internal unique identifier for the partner
lm_partner_id	string	No	LM account ID mapped to this partner
name	string	No	Partner display name (defaults to LM account ID on creation)
created	boolean	No	Whether this entity was created by the current call

DB source: partners.id, partners.lm_partner_id, partners.name

Used in: SetupResponse.partner

---

SetupClient

Client entity resolved or created during setup.

{
  "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
  "lm_client_id": "Z6RWR",
  "name": "Z6RWR",
  "created": true
}

Field	Type	Nullable	Description
id	string (uuid)	No	Internal unique identifier for the client
lm_client_id	string	No	LM client ID mapped to this client
name	string	No	Client display name (defaults to LM client ID on creation)
created	boolean	No	Whether this entity was created by the current call

DB source: clients.id, clients.lm_client_id, clients.name

Used in: SetupResponse.client

---

SetupPartnerUser

Partner user entity resolved or created during setup.

{
  "id": "c9d0e1f2-a3b4-5678-90ab-cdef12345678",
  "lm_user_id": "m5ktu",
  "email": "liam+demo@example.com",
  "created": true
}

Field	Type	Nullable	Description
id	string (uuid)	No	Internal unique identifier for the partner user
lm_user_id	string	No	LM user ID mapped to this partner user
email	string	No	User email address from LM claims
created	boolean	No	Whether this entity was created by the current call

DB source: partner_users.id, partner_users.lm_user_id, partner_users.name

Used in: SetupResponse.partner_user

---

SetupResponse

Top-level response returned by the setup endpoint. Contains all three resolved or created entities.

{
  "partner": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "lm_partner_id": "4cjbb",
    "name": "4cjbb",
    "created": true
  },
  "client": {
    "id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
    "lm_client_id": "Z6RWR",
    "name": "Z6RWR",
    "created": true
  },
  "partner_user": {
    "id": "c9d0e1f2-a3b4-5678-90ab-cdef12345678",
    "lm_user_id": "m5ktu",
    "email": "liam+demo@example.com",
    "created": true
  }
}

Field	Type	Nullable	Description
partner	SetupPartner	No	The partner entity resolved from accountId
client	SetupClient	No	The client entity resolved from clientId
partner_user	SetupPartnerUser	No	The partner user entity resolved from userId

Omitted internal fields: partner_id, client_id, cognito_id, config, status, role, created_by, updated_by, created_at, updated_at

Used in: Setup

Related Endpoints

• Get Client — Fetch full client details after setup resolves the client ID