Create partner

Post

/platform/api/partners/preview

Creates a partner and returns it with its server-assigned id.

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.

Body parameters

partner

A partner

partner

{
  "name": "ACME Logistics",
  "status": "ACTIVE",
  "policy": "Global"
}

Expand All

object

A business party the platform exchanges data with. The partner itself holds only its name, status and rate-limit policy; its connections (logins, addresses, identifiers) are channels, managed under /platform/api/partners/preview/{partnerId}/channels, which profiles reference instead of the partner. {"name": "ACME Logistics"} is enough to create one; deleting a partner also deletes all its channels.

class

string

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

Valid values[ "core.IntegrationPartner" ]

contacts

Array of object (core.IntegrationPartnerContact)

Contacts of the partner (people, not logins). null or left out keeps the stored contacts; a list replaces them: contacts not in the list are deleted, entries with a known id are updated, entries without one are created. Not carried on the partner embedded in a channel body.

object

A contact person (a person to reach, not a login): a partner's contacts are held in the partner's contacts member, the contact of a single channel in that channel's contact member.

class

string

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

Valid values[ "core.IntegrationPartnerContact" ]

emailAddresses

Array of string

E-mail addresses of the contact, one entry per address; in the stored form (comma-separated, display names quoted) they must fit 250 characters.

Example["erika.mustermann@acme.example"]

string

fax

string

Fax number of the contact.

Max length20

Example+49 30 1234568

integer (int64)

Id of the contact, assigned by the server. Ignored on create. On a partner update an id must be one of this partner's stored contact ids and updates that contact, left out creates a new one; on a channel update it must be the id of the channel's own contact, left out updates that contact.

language

string

Language of the contact, as stored by the platform; left out or blank, none is set.

Max length10

Examplede

name

string

Name of the contact person.

Max length250

ExampleErika Mustermann

note

string

Free-text note about the contact.

phone

string

Phone number of the contact.

Max length20

Example+49 30 1234567

name

string Required

Display name of the partner. Must be unique among all partners that are not deleted.

Min length1

Max length250

ExampleACME Logistics

policy

string

Name of the rate-limit policy for requests this partner sends to the platform's REST API and MCP endpoints through its HTTP channels; it applies when the HTTP channel itself names no policy. Global is built in; another name must reference an existing policy. Left out on create or blank, the partner has no policy; an explicit null keeps the stored value.

ExampleGlobal

status

string

Whether the partner is in use. An explicit null keeps the stored value. DELETED cannot be written - delete the partner with DELETE instead.

Valid values[ "ACTIVE", "INACTIVE", "DELETED" ]

Default"ACTIVE"

Responses

201

Partner created.

Headers

Location

(uri)

URI of the created partner.

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.IntegrationPartner)

class

string

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

Valid values[ "core.IntegrationPartner" ]

contacts

Array of object (core.IntegrationPartnerContact)

object

A contact person (a person to reach, not a login): a partner's contacts are held in the partner's contacts member, the contact of a single channel in that channel's contact member.

class

string

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

Valid values[ "core.IntegrationPartnerContact" ]

emailAddresses

Array of string

E-mail addresses of the contact, one entry per address; in the stored form (comma-separated, display names quoted) they must fit 250 characters.

Example["erika.mustermann@acme.example"]

string

fax

string

Fax number of the contact.

Max length20

Example+49 30 1234568

integer (int64)

language

string

Language of the contact, as stored by the platform; left out or blank, none is set.

Max length10

Examplede

name

string

Name of the contact person.

Max length250

ExampleErika Mustermann

note

string

Free-text note about the contact.

phone

string

Phone number of the contact.

Max length20

Example+49 30 1234567

integer (int64)

Numeric id of the partner, assigned by the server on create; it is the {partnerId} in the partner's URLs and its channels' URLs. A value sent in a body is ignored.

isManagedByTpm

boolean

true when the partner is managed by the connected Trading Partner Manager (TPM). Such a partner and its channels cannot be deleted through this API. Set only by the TPM synchronisation; a value sent here is ignored.

name

string

Display name of the partner. Must be unique among all partners that are not deleted.

Min length1

Max length250

ExampleACME Logistics

policy

string

ExampleGlobal

status

string

Whether the partner is in use. An explicit null keeps the stored value. DELETED cannot be written - delete the partner with DELETE instead.

Valid values[ "ACTIVE", "INACTIVE", "DELETED" ]

Default"ACTIVE"

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?