Developers: API and access tokens
Give your own developers access to your workspace with an access token, and get a message in your own systems when something changes.
- What you use access tokens and webhooks for
- Create, store and revoke an access token
- Set up, test and follow up a webhook
- Work safely with tokens and secrets
Under Settings › Developers you give your own developers access to your workspace. That way they connect Ringlane to your own systems, for example Zapier, an internal dashboard or a data warehouse.
- Access tokens: with an access token, your own integration reads and writes in Ringlane, within the access you choose.
- Webhooks: Ringlane sends a message to your own system as soon as something changes, for example a new record or a scheduled meeting.
The technical reference for developers is at ringlane.ai/developers.
Who and which plan
Owners and admins see Developers in Settings, under Workspace. Only the owner creates and manages access tokens and webhooks: they give access to the data of the whole workspace. An admin therefore sees Only for the owner.
Access tokens and webhooks are part of Pro and Business, also during the Pro trial. On Free and Plus you see This is in Pro, with the button View plans.
Developers is for people who build their own software. To connect Google, Attio or Aircall, use Apps.
Create an access token
- Go to Settings › Developers › Access tokens.
- Click New access token.
- Under Name, give the token a name that says what it's for, for example "Zapier" or "Our data warehouse".
- Under Expires after, choose how long the token works: 7 days, 30 days, 90 days or 1 year. 90 days by default.
- Per area, choose Off, Read or Read and write. Everything starts at Off; give at least one area access.
- Click Create token.
- In the Copy your access token window, click Copy, store the token and click I have stored it.
You see an access token only once, when you create it. Ringlane cannot show it to you again, not even to you. Store it in a password manager or in your integration's secrets, never in code, a document or a chat. Lost it? Revoke it and create a new one.
The areas
| Area | What a token can do | Access |
|---|---|---|
| Records | View leads, and optionally create, change and delete them | Read, or read and write |
| Campaigns | View campaigns, and optionally create and change them | Read, or read and write |
| Activities and notes | View calls, outcomes and notes on a record, and optionally add notes | Read, or read and write |
| Tasks | View call-backs and follow-up tasks, and optionally schedule or clear them | Read, or read and write |
| Meetings | View meetings scheduled with leads | Read |
| Members | View the members of the workspace: name, email address and role | Read |
| Fields and statuses | View the custom fields, statuses and task kinds | Read |
Give only what the integration needs. A token gives access to the data of the whole workspace, within this access. A workspace can have at most 25 valid access tokens.
Manage and revoke tokens
Under Access tokens you see each token with its name and its access, such as Records: read and write. You see when and by whom it was created, when it was last used (or Not used yet) and until when it works. Of the token itself you only see a small part, so you recognise it.
Revoke a token when you no longer need it, when a developer leaves or when you think someone else knows it: click the three dots and choose Revoke. The token stops working right away and the integration that uses it loses its access. This cannot be undone.
A token also stops by itself. It then gets a label:
- Expired: its validity has run out.
- No longer works: the person who created it is no longer an owner of this workspace. Create a new token.
At the bottom is the Log: the last 50 actions with tokens, webhooks and the API in this workspace, such as a token being created or revoked, with who did it and when.
Webhooks: messages to your own systems
With a webhook, Ringlane sends a signed message to your own system as soon as something changes. Your system then doesn't have to keep checking for anything new. A message only contains ids, never names or numbers.
- Go to Settings › Developers › Webhooks and click Create webhook.
- Under Target URL, fill in the address where your system receives the messages: a public address that starts with https.
- Under Events, tick what you want a message about. Search events helps you find one quickly.
- Click Create webhook.
- In the Copy your webhook secret window, copy the secret, give it to your developer and click I have stored it. Your system checks every message with it, so it knows the message really comes from Ringlane. Ringlane doesn't show the secret again.
- Use the three dots on the webhook and choose Send test message to see whether your system receives it.
| Event | When |
|---|---|
| Record created, Record updated, Record deleted | A lead was added, changed or deleted |
| Activity added | A call, outcome or note was added to a record |
| Meeting scheduled | A meeting with a lead was scheduled |
| Campaign created, Campaign updated, Campaign deleted | A campaign was added, changed or deleted |
A workspace can have at most 10 webhooks. If Webhooks shows Webhooks are coming soon, access tokens already work and webhooks follow later.
Follow up a webhook
For each webhook you see its address, its events and its status: Active, Off or Switched off after failures. You also see when something was last delivered, how many messages are still queued and how many failed in the last 7 days. With the three dots you choose:
- Send test message: Ringlane tells you right away whether the test message was delivered.
- View deliveries: the latest messages, each with Waiting, Working, Delivered, Failed or Cancelled, the number of attempts and when Ringlane tries again. Send a failed message again with Retry.
- Edit: change the address or the events.
- New secret: the current secret stops working right away. Give the new secret to your developer straight away.
- Turn off or Turn on. What was still waiting when you turned it off will not be sent.
- Delete: Ringlane stops sending to this address and the list of deliveries disappears.
If every delivery fails for three days, Ringlane switches the webhook off: Switched off after failures. Check the deliveries, fix the problem and switch the webhook back on.
Working safely
- Treat a token and a webhook secret like a password. Store them in a password manager or in your integration's secrets, never in code, a document or a chat.
- Create one token per integration, with a name that says what it's for. That way you revoke one without disturbing the rest.
- Give only the access that's needed. If an integration only needs to read, choose Read.
- Choose the shortest validity that works, and create a new token in time.
- Check regularly when each token was last used, and revoke tokens nobody uses anymore.
- If you think someone else knows a webhook secret, choose New secret.
If it doesn't work
- You don't see Developers: only owners and admins see this page.
- You see Only for the owner: only the owner creates and manages tokens and webhooks.
- You see This is in Pro: access tokens and webhooks are part of Pro and Business.
- A token no longer works: check whether it shows Expired or No longer works, or was revoked. Create a new one if needed.
- You can't create a new token: you already have 25 that still work. Revoke one you no longer use.
- A webhook address is refused: use a public address that starts with https. An internal address of your company isn't allowed.
- A webhook shows Switched off after failures: check the deliveries, fix the problem and switch it back on.
- Your plan moves to Free or Plus: Ringlane shows beforehand what changes. Access tokens and webhooks then stop.