Apps

An app is one integration, packaged: the access it needs, its credentials and the webhook events it receives. Make one for your own systems (an ERP, a PLM, a script, an agency building for you), or build an app that other companies connect to their Veribl account.

Apps use the REST API and webhooks, with the same access areas as API keys. Veribl's own Zendesk and Akeneo integrations are built the same way.

Private apps and OAuth apps

Create an app

1. Go to Settings › Integrations and click Create app under Your apps.
2. Name it and pick Only your company (private) or Other companies (OAuth).
3. For an OAuth app, add the redirect URLs your app receives the authorization code on. They must be https (http works for localhost).
4. Under Access, turn on only the areas the app needs: read, or read and write.
5. Optionally add a webhook URL. The app gets every event its access covers, or the events you pick.
6. Click Create app.

A private app's access token, or an OAuth app's client secret, is shown once. Copy it straight away. If it's lost, open the app and click New token or New secret.

The app's page shows its credentials, access, webhook signing secret, and its recent API calls and webhook deliveries in your account. Every change it makes is in the audit log as "App: name".

Use a private app

Send the token like an API key:

curl "https://app.veribl.com/api/v1/products?limit=10" \
  -H "Authorization: Bearer vdpp_your_app_token"

Changing the app's access applies to its token from the next request.

Connect an OAuth app

OAuth apps use the authorization code flow (OAuth 2.1).

1. Send the person to Veribl

https://app.veribl.com/connect/authorize
  ?client_id=app_your_client_id
  &redirect_uri=https://your-app.com/oauth/veribl/callback
  &response_type=code
  &state=random_value_you_check_later

Your app's page in Veribl has this link ready to copy. You can add PKCE (code_challenge and code_challenge_method=S256); with a client secret it's optional.

The person signs in, sees your app's name, your company and the access it asks for, and clicks Allow. They need permission to manage integrations and the API & webhooks add-on. Veribl sends them back to your redirect URL with code and state.

2. Swap the code for tokens

curl https://app.veribl.com/api/connect/token \
  -u "app_your_client_id:vsec_your_client_secret" \
  -d grant_type=authorization_code \
  -d code=THE_CODE \
  -d redirect_uri=https://your-app.com/oauth/veribl/callback

{
  "access_token": "vdpp_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "vrt_…",
  "scope": "products:write passports:read",
  "install_id": "inst_7c1e…",
  "company_name": "Halden"
}

The code works once, within 10 minutes. install_id identifies the company that connected your app: keep the tokens per install. You can also send client_id and client_secret in the form body instead of HTTP Basic.

3. Refresh the access token

Access tokens last an hour. Get new ones with the refresh token:

curl https://app.veribl.com/api/connect/token \
  -u "app_your_client_id:vsec_your_client_secret" \
  -d grant_type=refresh_token \
  -d refresh_token=vrt_…

Each refresh returns a new refresh token, valid for 90 days. Use each refresh token once: using one twice revokes every token of that install, and the company has to connect your app again.

When a company disconnects

A company can disconnect your app in Settings › Integrations › Connected apps. Its tokens stop working at once (401) and its webhooks stop.

If you later ask for more access, companies that connected your app keep what they approved until they connect it again.

Webhooks for apps

Deliveries are signed with the app's signing secret, the same for every company, so you verify them all with one secret. See Webhooks for the signature.

An app only receives events about what it can read: