Patch profile group

Patch

/platform/api/profiles/preview/groups/{id}

Renames a group (name) and/or moves it (parentId, null for the top level); members not sent keep their value, and id, groups and profiles are ignored. Renaming needs the group right on the group, moving it also on the new parent, as in the Lobster UI (403). A name is unique among the groups of the parent (409), and a rename together with a move that no order of the two can apply without a name clash is refused (409); a group cannot move into itself or one of its own groups, and an unknown parent answers 422. An empty patch or a member other than name and parentId answers 400, an unknown id 404.

Security

OAuth

OAuth2 client-credentials flow for machine-to-machine access. Exchange a client id/secret at /dw/register/oauth/token for a bearer token, then send it as Authorization: Bearer <access_token>. Client credentials are provisioned in the Lobster administration UI.

This is the client-credentials token endpoint of the Platform API. /oauth/token, the token_endpoint advertised at /.well-known/oauth-authorization-server, serves the authorization code flow of the OAuth2AuthorizationCode scheme.

FlowClient Credentials

Token URL/dw/register/oauth/token

Refresh URL/dw/register/oauth/token

OAuth

OAuth 2.1 authorization code flow with PKCE, for acting as a signed-in user. It works with Microsoft and other single sign-on providers: the provider only confirms the user's identity to the platform, which then issues its own token.

POST /oauth/register (no authentication) with the JSON body {"redirect_uris": ["<redirect URI>"]} returns a client_id. The user's browser has to reach the redirect URI.
Open /oauth/authorize in the user's browser with response_type=code, client_id, redirect_uri, state and a code_challenge with code_challenge_method=S256. state is a fresh unguessable value per request, and code_challenge is the S256 hash of a code_verifier freshly generated per request from a cryptographically secure random source (43 to 128 characters, RFC 7636). The user signs in on the platform's login page, and the browser is redirected to the redirect URI with code and state; a callback whose state differs from the one sent is to be rejected.
The code is valid for 30 seconds. Exchange it at POST /oauth/token, form-encoded, with grant_type=authorization_code, code, redirect_uri, code_verifier and client_id.
The answer carries access_token (valid 30 minutes), refresh_token (valid 48 hours) and expires_in in milliseconds. Refresh with grant_type=refresh_token, refresh_token and client_id.

FlowAuthorization Code

Authorization URL/oauth/authorize

Token URL/oauth/token

Refresh URL/oauth/token

HTTP

Type bearer

Bearer token obtained from an authenticated browser or guest-user session.

Flow 1 — UI login: Log in via the Lobster web UI at /, then call GET /auth/sessionBearerToken to exchange the session cookie for a bearer token.

Flow 2 — Guest user login token: Append a GuestUser loginToken as a URL query parameter to the base URL to establish a password-free session:

GET <host>?loginToken=<GuestUser token>

Then call GET /auth/sessionBearerToken to obtain the bearer token.

Path parameters

stringRequired

The group's id, as returned by list and create; root (read only) is the top level.

Body parameters

A JSON object with name and/or parentId.

groupRename

Rename a group

groupRename

{
  "name": "Archive 2026"
}

object

Merge-patch form of core.ProfileGroup: every member is optional.

class

string

The type of this object, always core.ProfileGroup. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileGroup" ]

name

string

The name the Lobster UI shows for the group; unique among the groups of one parent.

ExampleOrders

parentId

string

The id of the group this group sits in; absent for a group on the top level. On create, the group to create it in. Send null in a patch to move the group to the top level.

Responses

200

Group updated.

Expand All

object

Standard Platform API success envelope. Every response carries exactly one of data (success) or error (failure) at top level.

data

object (core.ProfileGroup)

A profile group, a node of the profile tree. A profile's group holds its id.

class

string

The type of this object, always core.ProfileGroup. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileGroup" ]

groups

Array of object (core.ProfileTreeRef)

The groups directly in this group, by name. Present on a single-group response only; a sent value is ignored.

object

A reference to a subgroup or a profile of a group: its id, name and the path to fetch it.

class

string

The type of this object, always core.ProfileTreeRef. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileTreeRef" ]

href

string

The server-relative path that returns the referenced group or profile.

string

The identifier of the referenced group or profile.

name

string

The name of the referenced group or profile.

Exampleacme-order-import

string

The group's identifier: the value a profile's group holds and the path parameter of GET /groups/{id}; root for the top level. Assigned by the server; a sent value is ignored.

name

string

The name the Lobster UI shows for the group; unique among the groups of one parent.

ExampleOrders

parentId

string

The id of the group this group sits in; absent for a group on the top level. On create, the group to create it in. Send null in a patch to move the group to the top level.

profiles

Array of object (core.ProfileTreeRef)

The profiles directly in this group the caller may view, by name. Present on a single-group response only; a sent value is ignored.

object

A reference to a subgroup or a profile of a group: its id, name and the path to fetch it.

class

string

The type of this object, always core.ProfileTreeRef. Required where the member it is sent in accepts several types.

Valid values[ "core.ProfileTreeRef" ]

href

string

The server-relative path that returns the referenced group or profile.

string

The identifier of the referenced group or profile.

name

string

The name of the referenced group or profile.

Exampleacme-order-import

400

The request could not be understood. BAD_REQUEST for a body that does not decode — its message names the property at fault — and VALIDATION_FAILED with one details entry per offending parameter for a malformed request target (an unknown query parameter or sort key). Also BAD_REQUEST for a response unit naming a channel this client cannot reference.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

Stable machine-readable UPPER_SNAKE error code for programmatic handling, e.g. PARTNER_NOT_FOUND, VALIDATION_FAILED or FORBIDDEN. New codes may be added over time; treat an unknown code according to the HTTP status class. The HTTP status itself is carried by the status line only, never duplicated here.

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

401

Authentication is required or the supplied credentials are invalid.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

403

The caller lacks the permission for this operation on this resource (FORBIDDEN).

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Access to this resource is denied."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

404

The requested resource does not exist. The code is resource-specific, e.g. PARTNER_NOT_FOUND, PROFILE_NOT_FOUND or CHANNEL_NOT_FOUND.

{
  "error": {
    "code": "PARTNER_NOT_FOUND",
    "message": "Partner not found: 42"
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

409

The request collides with the current state of the resource: a name already taken by another record, a lastModified that no longer matches because the record changed since it was read, or a delete the record's state refuses (it is open in the Lobster UI, still referenced by other objects, or managed by the Transport Manager). A field-level collision carries one details entry naming it.

{
  "error": {
    "code": "CONFLICT",
    "message": "The request conflicts with the current state of the resource.",
    "details": [
      {
        "code": "FIELD_INVALID",
        "message": "A partner with the name 'ACME' already exists.",
        "target": "name"
      }
    ]
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

422

The body decoded but breaks a rule of the resource: a required member is missing, a value is not one of the accepted values or violates its pattern, length or range, a referenced id (partner, certificate, profile) does not exist, or two members contradict each other. One details entry per violation: FIELD_REQUIRED or FIELD_INVALID, with target naming the member path and message the rule, including the accepted values where there is a fixed set.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      {
        "code": "FIELD_REQUIRED",
        "message": "Field 'name' must not be empty.",
        "target": "name"
      }
    ]
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

500

An unexpected server error occurred.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

Expand All

object

Standard Platform API error envelope: every failed request carries a single error object. Every response carries exactly one of data (success) or error (failure) at top level.

error

object (Error)

What went wrong: branch on its code, show its message, and read details for one entry per failed member.

code

string

message

string

Human-readable, non-localized explanation. Branch on code, never on this text.

details

Array of object (ErrorDetail)

Individual failures within the request, e.g. one entry per violated field.

object

A single failure within the request.

code

string

Stable machine-readable UPPER_SNAKE code of this individual failure, e.g. FIELD_REQUIRED, FIELD_INVALID or VALUE_OUT_OF_RANGE.

message

string

Human-readable, non-localized explanation of this individual failure.

target

string

What this failure refers to, e.g. the violated field.

Was this article helpful?