apps

Create an app

Creates the app and its credentials.

How many apps fit is decided by the plan, not by a fixed limit of one: 1 on free, 2 on basic, 5 on pro and 10 on custom. Going over answers ERROR_CODE_1308, which carries limit and used in its data. Deleting an app frees its slot immediately, because only live apps count. If you just need to rotate credentials, update the existing app rather than creating another.

The user's email must be verified (ERROR_CODE_546). This is the only route in /apps that asks for it: an app is a key to the whole public API, and this is what stops a throwaway address from minting them in bulk. Reading, updating and deleting an app you already own do not check it.

The identifier has a format (error 533): lowercase letters, numbers, ., - and _, starting with a letter or a number, 3 to 64 characters. Pick it carefully — it cannot be changed later (error 547).

Every URL is validated: a bad entry in allowed_domains answers 531, in redirect_urls 532, and a bad webhook_url answers 535.

The secret is not in the response. Read it with GET /clients/{id_client}/apps/{id_app}/secret.

Needs a USER token, not an app token. With client credentials it answers ERROR_CODE_512. No plan is required: apps are on all four plans, the free one included — what the plan decides is how many you can hold at once and how fast you can call.

post/clients/{id_client}/apps

Request

  • Base URL: https://api.planvortex.com/v1.0.0
  • URL: https://api.planvortex.com/v1.0.0/clients/{id_client}/apps
  • 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

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 created app

Changes

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