Skip to main content

Replace the M2M workloads of an onboarding case

PUT 
/v1/onboarding-cases/:case_id/m2m-clients

Declares the bank's machine-to-machine (M2M) workloads: back-end systems that call the Lyriq Connector without a human user. A workload authenticates with a short-lived assertion issued by the bank's FIS identity provider; the platform IAM verifies it against workload_identity_provider and exchanges it for a Lyriq Connector access token. Workloads are secretless: no client secret or private key is sent to or held by the platform.

Required scope: connector:onboarding:artifacts:write.

Allowed states: AWAITING_BANK_ADMIN, BANK_CONFIGURING, NEEDS_CHANGES (otherwise 409). The first edit moves AWAITING_BANK_ADMIN to BANK_CONFIGURING.

Full replacement. The request replaces the complete list. Send every workload you want to keep; send m2m_clients: [] (and workload_identity_provider: null) to remove them all. No Idempotency-Key is used; repeating the same request is safe and has the same effect (the case version still increases).

workload_identity_provider (required key; may be null only when m2m_clients is empty, otherwise 422):

  • jwks_url (required): the JWKS endpoint the platform IAM uses to verify your workload assertions. Absolute https URL, at most 2048 characters (plain http is accepted only for localhost in a sandbox case).
  • issuer (optional): the exact iss value of your workload assertions. Omitted or blank means the case's fis_idp_entity_id. At most 2048 characters.

When m2m_clients is empty the provider is not stored.

Each m2m_clients[] entry (at most 20 entries; surrounding whitespace is trimmed from all strings):

  • display_name (required, 1 to 128 characters): a name for the workload.
  • business_purpose (required, 1 to 512 characters): what the workload does.
  • fis_client_id (required, 1 to 256 characters): the workload's client identifier at FIS. The sub claim of the workload's assertion must equal this value exactly (case-sensitive). Must be unique within the request and within your bank.
  • roles (required, at least one, unique): preset labels maker, checker, readonly. Labels describe the workload; they do not grant permissions. Administrative roles (bank-admin) cannot be given to a workload.
  • scopes (required, at least one, unique): the permissions the workload's access tokens carry. This is the only thing that authorises its API calls. Any assignable scope may be combined with any role. Assignable scopes: connector:accounts:create, connector:accounts:list, connector:accounts:read, connector:accounts:holding-registrations:create, connector:accounts:holding-registrations:list, connector:accounts:holding-registrations:read, connector:assets:list, connector:assets:read, connector:auth-profiles:bind, connector:auth-profiles:create, connector:auth-profiles:list, connector:auth-profiles:read, connector:auth-profiles:update, connector:balances:list, connector:banks:list, connector:banks:read, connector:exposures:list, connector:liabilities:list, connector:limits:list, connector:limits:read, connector:limits:update, connector:operations:cancel, connector:operations:list, connector:operations:read, connector:redemptions:create, connector:redemptions:list, connector:redemptions:read, connector:redemption-policies:list, connector:redemption-policies:read, connector:reviews:decide, connector:reviews:list, connector:reviews:read, connector:settlement_cycle:list, connector:settlement_cycle:read, connector:transfers:create, connector:transfers:list, connector:transfers:read, connector:transfers:screening-decide, connector:webhook_deliveries:list, connector:webhook_deliveries:read, connector:webhooks:create, connector:webhooks:list, connector:webhooks:read, connector:webhooks:rotate-secret, connector:webhooks:test, connector:webhooks:update. Any other scope (operator, onboarding, staff, connector:m2m-clients:read, unknown) returns 422.

Do not send a platform client id. The platform generates one per workload (keycloak_client_id in the response, shown as Platform client ID in the Bank Portal) of the form bank-m2m-{uuid}. It keeps the same value for a workload across later replacements as long as its fis_client_id is unchanged.

Provisioning outcome. Saving workloads provisions nothing. When the case is accepted and its activation operation succeeds, the platform IAM creates one client per workload with the generated platform client id. Each client is created disabled, receives its approved scopes and bank membership, and is then enabled. The case reaches ACTIVE only after every workload (and every staff member) has been provisioned; from then on the workload can obtain access tokens (valid 300 seconds) and appears in GET /v1/m2m-clients.

The response is the updated case; the saved workloads are in data.attributes.configuration.m2m_clients.

Request​

Responses​

The workload list was replaced. Returns the updated onboarding case, including readiness.