Help center › System and administration

API clients and webhooks

Service accounts and apps that call the API with OAuth 2.0, firm limits, legacy keys, and signed webhooks to your HTTPS endpoint.

Systems reach Vestoris through the REST API with OAuth 2.0. Every call needs its scope and the privileges of the user or service account behind it, checked by the same rules as the screens. Secrets are shown once; Vestoris keeps only keyed hashes. Everything here is in the event log. Paper trading: the API places simulated orders only.

Add a client

1. Kind: Service account (client credentials) for a system, or App acting for people (authorization code + PKCE).
2. Name; for a service account its role (it gets that role's privileges and, like any user, only the accounts it is entitled to on Users and permissions).
3. Client authentication: a secret (HTTP Basic or in the form) or a signed JWT (private_key_jwt, RFC 7523) with your public key.
4. Scopes the client may ask for (e.g. orders:read, portfolio:read, data:load:prices).
5. For apps: the exact HTTPS redirect URIs. Optional: an IP allow-list (CIDR), CORS origins for browser apps (CORS is off unless an origin is listed), the access-token lifetime (at most 3600 seconds), how long refresh tokens last (at most 30 days), and requests a minute.
6. This service account may approve orders and overrides: off by default. An approval by a system is still an approval: four eyes still applies, it never signs off compliance or workflow rules, and every approval is logged. An Admin-role service account needs an extra confirmation.
7. Create client, and copy the secret: it is shown once.

People see a consent screen when an app asks for access, and grant only what their role allows; they can withdraw it on My API access.

Firm limits

The longest access token, the longest refresh token and the default requests a minute per client.

Legacy API keys

The 1.2 keys (vst_…) still reach the data, feed and bundle endpoints, with Deprecation and Sunset headers; the page shows when any was last used, and Turn legacy keys off. See Legacy API keys.

Webhooks

Vestoris POSTs signed JSON events to your HTTPS endpoint: Vestoris-Signature: t=<unix>,v1=<HMAC-SHA256(secret, "t.body")>. Refuse timestamps older than 5 minutes. Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Endpoints must be public HTTPS addresses.

1. Add a webhook: the HTTPS URL, a description and the events (order.created, order.updated, fill.created, violation.created, violation.updated, workflow.item.updated, workflow.sla_breached, feed.run.updated, sod.status, rule.activated, rule.retired).
2. Copy the signing secret (shown once).
3. Ping sends a test event; the delivery log shows every attempt, and Redeliver sends one again. Pause, change or delete the webhook at any time.

How to verify the signature, with code: Webhooks.

Related articles

• My API access Personal access tokens for your own scripts, acting as you; and the apps you authorized.
• The Vestoris API, in short Everything the screens do, your systems can do through the REST API, under exactly the same rules. Where to start.
• Legacy API keys (deprecated) The 1.2 data API keys (vst_…) still load files over HTTPS but are deprecated; move them to an OAuth service account.
• The API console (demo) Try the REST API from the browser against your own demo sandbox, as your current persona.
• The event log Every action from every component, append-only and hash-chained; filter it, open a row, and verify the chain.

Do it with the API

Every action on this screen can also be done by your own systems, under the same permissions. See Authentication to get a token.

• GET/api/v1/webhooks Webhooks
• POST/api/v1/webhooks Add a webhook (the signing secret is returned once)
• PATCH/api/v1/webhooks/{id} Change events, URL or status
• DELETE/api/v1/webhooks/{id} Delete a webhook
• GET/api/v1/webhooks/{id}/deliveries The delivery log
• POST/api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver Send a delivery again
• POST/api/v1/webhooks/{id}/ping Send a test event

Paper trading only: orders and fills in Vestoris are simulated. Nothing here is investment advice.