Create your API applications

An API application is your firm's login for the API. Create one in the dashboard under Integrations, API applications, New application. Owners can create, edit and delete them; managers can see them.

Press Create application. Its page shows:

• Client ID: like a username. Not secret on its own, but keep it with the secret.
• Client secret: like a password. It is shown once only, straight after you create the application. Copy it into your server's secret store then.
• Edit: change its name, scopes and allowed origins. The client id and secret stay the same. If you remove a scope, the tokens it has already issued stop working at once, and your code asks for a new one (see How long a token lasts). New allowed origins work at once, and a scope you add can be asked for in the next token request. The same rules apply as when creating it, so a browser application still can't have crm or outcomes. A quote form's own application (its name starts "Quote form:") is changed on the quote form instead.
• Rotate: makes a new secret. The old secret stops working at once, and so does every token already issued with it. Update your server with the new secret straight away.
• Delete: removes the application and stops every token it has issued.

Scopes#

A scope is a permission. You tick the scopes an application may have, and each token request asks for some or all of them. A token request that names no scopes gets all of the application's.

Give each application only the scopes it needs. An application with allowed origins (a browser application) can only have read and write. While websites are listed under Allowed origins, crm and outcomes are switched off, so a browser can't reach your customers' records. To use them, leave Allowed origins empty and call Subcontext from your server.

Allowed origins#

An origin is the start of a web address: scheme, host and port, like https://www.example.com. No path and no slash at the end.

• Each entry must match what a browser sends. https://example.com and https://www.example.com are different, so list both if your pages are on both.
• You can paste a page address. It is cut down to the origin when you save, so https://www.example.com/quote/ becomes https://www.example.com. Entries are lower-cased, and a default port is dropped (https://example.com:443 becomes https://example.com). Anything that isn't http(s)://host[:port] is refused, with a message saying which entry.
• To try the examples on your own computer, use http://localhost:4100.

Server-only or browser: you'll usually want two#

Using the wrong kind of application is the most common mistake.

Subcontext checks where every API request comes from. When a page on your website calls Subcontext, the browser adds an Origin header saying which website the page is on. A request from your server normally has no Origin.

A firm that sends leads from its server and offers quotes through its own token endpoint needs two applications, one server-only and one browser. Using the wrong one gives a 403 that names the problem (see Errors and fixes).

A token you hand to a browser can be read by anyone using that page. Keeping browser tokens away from customer data, and server tokens out of browsers, limits the harm if one leaks.