apps

Update an app

Replaces the app's configuration. Every field is overwritten with what you send, so a redirect_urls you leave out becomes an empty list — send the whole object, not a patch.

Changing webhook_url takes effect on the next event; there is no verification handshake.

It replaces every field with what the body carries. name, keycloak_client_idenfifier, allowed_domains, redirect_urls and webhook_url are all written as sent, so omitting one erases it — sending an update without webhook_url turns the webhook off. Read the app first and send it back whole.

keycloak_client_idenfifier is the one field that is NOT overwritten. Sending a different one answers ERROR_CODE_547 and nothing is written: it is the client_id your integration authenticates with, and renaming it would lock out everything already asking for tokens with the old one. Send it unchanged, or leave it out. If you need a different identifier, create another app.

An app token works here. This is the one part of /apps that does: an app can read and update its own record, but it cannot list, create, delete, or read the secret. No plan is required: apps are on all four plans, the free one included.

put/clients/{id_client}/apps/{id_app}

Request

  • Base URL: https://api.planvortex.com/v1.0.0
  • URL: https://api.planvortex.com/v1.0.0/clients/{id_client}/apps/{id_app}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (client credentials, token URL https://api.planvortex.com/v1.0.0/oauth/token)

Path parameters

id_clientstring required

Client identifier

id_appstring required

App identifier

Request body

namestring required

A name for the app. Cannot be blank (error 525).

keycloak_client_idenfifierstring required

The app's client_id, which is what you send to POST /oauth/token.

Format is enforced (error 533): lowercase letters, numbers, ., - and _, starting with a letter or a number, between 3 and 64 characters — shop-integration, not Shop Integration. Keycloak itself accepts anything, so an identifier with a space in it used to create an app that could never get a token.

It also has to be unique across PlanVortex (error 534), and it cannot be changed once the app exists (error 547): it is what your integration authenticates with, so renaming it would lock out everything already using the old one. Send it unchanged on an update, or leave it out. The spelling of the field is historical and kept for compatibility.

allowed_domainsstring[]

Origins allowed to call the API with this app's identity. Every entry has to be a valid URL (error 531).

redirect_urlsstring[]

URLs the connect flow is allowed to come back to. A redirect_uri that is not in this list is refused when issuing a temporal connect token (error 532).

webhook_urlstring

Where PlanVortex posts events. Has to be a valid URL (error 535). See ClientApp.webhook_url for what arrives and how it is signed.

Example request

{
  "keycloak_client_idenfifier": "shop-integration"
}

Response

The updated app

Changes

No recorded changes to this operation across all 1 revision of this API.