This guide shows how your firm's systems get an access token from Subcontext and use it. An access token lets your code use the Subcontext API for two hours. Your code gets one by showing Subcontext its client id and client secret, the username and password of an API application you create in the dashboard. This is a standard called OAuth (the "client credentials" kind).
You need a token when:
- your server talks to Subcontext, for example to send leads from your own systems or a partner's, or to read what became of them; or
- a web page uses the API with your server's help, for example the quote form offering several products on one page, or your own JavaScript reading your products.
Most website embeds don't need a token. They use a public key or id that you paste into your page:
| Embed | What it uses | Can it use a token? |
|---|---|---|
| Webchat | Your agent's id | No |
| Form guide | Your agent's id | No |
| Lead form | The form's key (lfk_...) |
No. To send leads from a server, use a token with the leads API (Send leads from your server). |
| Quote form | The quote form's key (qfk_...) |
Yes, with getToken in place of the key (Hand a token to the quote form) |
| WebMCP | The integration's key (wmk_...) |
No |
| Nurture | The widget key (nwk_...) and a pass your server signs |
No (it has its own signing key) |
- Token address:
https://subcontext.com/oauth/token - API address:
https://subcontext.com/api/v1
Connecting an AI assistant such as Claude or ChatGPT to Subcontext uses a different kind of sign-in, where a person approves the connection. This guide doesn't cover it.
Quick start#
This gets a token for your server and sends a lead with it.
- In the Subcontext dashboard, open Integrations, API applications and press New application. (Only owners of your organisation can.)
- Give it a Name (like "Our CRM"), tick read, write and crm, and leave Allowed origins empty. Press Create application.
- Copy the Client ID and Client secret now. The secret is shown only this once. Keep it somewhere safe on your server.
- Ask for a token:
curl -X POST https://subcontext.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d "scope=read write crm" \
-d resource=https://subcontext.com/api/v1The answer:
{"access_token":"vX2...k9Q","token_type":"Bearer","expires_in":7200,"scope":"read write crm","created_at":1791792055}- Use the token. Send it in an
Authorizationheader on each API request:
curl -X POST https://subcontext.com/api/v1/crm/ingests \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-0001" \
-d '{"source": "my_website", "campaign": "YOUR_CAMPAIGN_KEY",
"identity": {"first_name": "Ada", "email": "ada@example.com"}}' A 202 Accepted answer means Subcontext has the lead.
send-lead.mjs does the same in Node. There are PHP and .NET versions in the example files.
Need help?#
Email hello@subcontext.com.
In this section
- Create your API applications Create the API applications your code signs in with, choose their scopes and allowed origins, and decide which are server-only and which are for the browser.
- Get a token Ask Subcontext for an access token with your application's client id and secret, and keep reusing it until shortly before it runs out.
- Send leads from your server Use a server-only application's token with the leads API to send leads from your own systems and check what became of them.
- Use a token in the browser Hand a browser application's token to the quote form or your own page scripts through a small token endpoint on your server, without ever showing the client secret.
- Errors, limits and security What the API offers, a security checklist, every error a token request or API call can give and how to fix it, and the limits.
- The example files Complete examples in curl, Node, Python, PHP and C# for getting a token, sending a lead and running a token endpoint, plus two pages to try in a browser.