API keys

A key lets your own software, such as your website's server, a script or a scheduled job, use Vision for your business. You make keys yourself in Vision under Settings → Developer. Only owners and administrators see that page.

Connect a website form

The quickest way in. In Settings → Developer, choose Connect a website form. Vision makes a key called Website form (or Website form 2 and so on, if the name is taken) that:

• runs on your website's server (identity class website_bff), and
• can only add leads for review in CRM (crm:intake:create). It can't read or change anything else.

Vision then shows, once, everything your website needs: the server settings with the secret, a plain HTML form, and server code that sends each submission to CRM. Paste them in, send a test, and the lead appears in CRM under Leads. The full contract is in Collect leads from your website.

Create a key

For anything else, choose Create a custom key:

1. Name. What uses it, in your words ("Zapier sync"). Names are unique among your active keys.

2. Where it runs. This decides which permissions can be chosen.

   Choice	Identity class	For
   Website server	website_bff	Your website's own server, such as a contact form
   Integration	machine_api_client	A script or another system that reads or writes
   Background job	worker	A scheduled or queued job that runs with nobody present

3. What it can do. Permissions are grouped by App, Vision's own first. Each App says which kinds of key it accepts; one that can't take this key says why. Nothing is ticked for you. On live Vision, Vision's own read API (/vision-core/v1) isn't open yet and answers 404, so today a key's useful permission there is CRM's lead intake.

4. Confirm it's you. Creating a key, replacing a secret and revoking a key each need you to confirm it's you: sign in again, or enter your current password each time if Vision holds one for you. Creating a key and replacing a secret on your live Vision also need two-step sign-in to be turned on. Revoking doesn't, so anyone allowed here can always stop a leaked key.

You never choose the environment: a key made on live Vision works with live Vision only.

What you get, once

Copy the secret before you close the panel. If you lose it, replace the secret.

Use the key

Your software swaps the client ID and secret for a short-lived token (5 minutes at most), then sends the token as Authorization: Bearer .... Name the App the token is for with resource; leave resource out for Vision itself.

curl https://app.runonvision.com/oauth/token \
  --request POST \
  --user "$VISION_CLIENT_ID:$VISION_CLIENT_SECRET" \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=crm:intake:create' \
  --data-urlencode 'resource=vision-crm-live'

Cache the token until shortly before it expires and ask for a new one then; there is no refresh token. Every parameter and error is on Authentication.

Telling Apps about a key

Some Apps, CRM among them, keep their own record of each key that may reach them. When you make a key for such an App, Vision tells the App first, and the key works once the App confirms, usually within seconds. Until then the key reads "Telling CRM…". If the App doesn't answer within about two minutes, Vision withdraws the key: nothing usable is kept, no secret was shown, and you can make it again.

Revoking a key tells the same Apps that it is gone. If an App hasn't confirmed yet, Vision keeps trying, and the key's details offer Try again.

Replace a secret

Replace secret makes a new secret and shows it once. The client ID stays the same. Choose when the old secret stops working: right away, in 15 minutes or in 60 minutes, so you can put the new one in place first. After that, anything still using the old secret is refused.

Revoke a key

Revoke key stops the key everywhere, right away, and tells its Apps. It can't be undone. Tokens it already holds stop within 5 minutes, when they expire. Revoked keys stay listed under Revoked keys for your records.

Which keys you see

Settings → Developer lists only the keys made for your business. Vision's own service connections between its Apps never appear there, and can't be changed from it.