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.

NewPlan Pro and BusinessFor Owner6 min
What you'll learn
  • 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

  1. Go to Settings › Developers › Access tokens.
  2. Click New access token.
  3. Under Name, give the token a name that says what it's for, for example "Zapier" or "Our data warehouse".
  4. Under Expires after, choose how long the token works: 7 days, 30 days, 90 days or 1 year. 90 days by default.
  5. Per area, choose Off, Read or Read and write. Everything starts at Off; give at least one area access.
  6. Click Create token.
  7. 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

AreaWhat a token can doAccess
RecordsView leads, and optionally create, change and delete themRead, or read and write
CampaignsView campaigns, and optionally create and change themRead, or read and write
Activities and notesView calls, outcomes and notes on a record, and optionally add notesRead, or read and write
TasksView call-backs and follow-up tasks, and optionally schedule or clear themRead, or read and write
MeetingsView meetings scheduled with leadsRead
MembersView the members of the workspace: name, email address and roleRead
Fields and statusesView the custom fields, statuses and task kindsRead

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.

  1. Go to Settings › Developers › Webhooks and click Create webhook.
  2. Under Target URL, fill in the address where your system receives the messages: a public address that starts with https.
  3. Under Events, tick what you want a message about. Search events helps you find one quickly.
  4. Click Create webhook.
  5. 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.
  6. Use the three dots on the webhook and choose Send test message to see whether your system receives it.
EventWhen
Record created, Record updated, Record deletedA lead was added, changed or deleted
Activity addedA call, outcome or note was added to a record
Meeting scheduledA meeting with a lead was scheduled
Campaign created, Campaign updated, Campaign deletedA 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.