Skip to content

Help

How to create and revoke API keys

Owners and admins can create and revoke API keys. Members can see key summaries. A new key is shown only once, so copy it before leaving the creation screen.

3 minute read

Enter opens the first match. Use Tab or the arrow keys to browse matches.

    The API keys screen lets another system read your business’s calls, callbacks and bookings. Owners and admins can create and revoke keys; members can see key summaries. Find it under Integrations, in For developers, through Manage API keys.

    Create and copy a key

    1. Open Integrations, find For developers, then select Manage API keys.
    2. In Create a key, enter a Key name so you can tell it apart from your other keys. A name is required and can contain up to 80 characters.
    3. Leave Allow this key to manage webhooks unticked for a key that only reads data. Tick it only if the key needs permission to create and stop webhook subscriptions (automatic updates sent to another system).
    4. Press Create API key. The form is replaced by Copy your key now.
    5. Press Copy. The button says Copied after a successful copy. If copying fails, the displayed key can still be selected and copied manually.

    Copy the key before leaving this screen.

    If the page says Not switched on yet, the API is not available and you cannot create keys. The message says there is nothing for you to do.

    What appears in the list

    Each row shows the key's name, its first few characters followed by …, and Created with a date. It also shows Last used with a date, or Never used.

    A key with webhook permission can show Can manage webhooks.

    If there are no keys, the screen says No API keys yet. Owners and admins are prompted to create one; members are told an owner or admin can do so.

    Use the key

    Send the key in the request header as Authorization: Bearer <key>, replacing <key> with your full key. The key only gives access to your business, with the permissions you chose.

    What another system can read

    • GET /api/v1/calls returns phone calls, most recent first. It includes call times, duration, caller details, outcome, reason, summary and whether follow-up is required.
    • GET /api/v1/callbacks returns callbacks, most recent first. It includes contact details, reason, requested time and status.
    • GET /api/v1/bookings returns bookings, latest start time first. It includes service, start and end times, timezone and status. It is not a complete export of the separate scheduling diary.
    • GET /api/v1/me returns the business ID and name, plus the key's first few characters and permissions. It never returns the full key.

    The calls, callbacks and bookings lists return 25 records by default, with a maximum of 100. If the requested limit is invalid, zero or negative, 25 are returned. There is no way to request further pages or filter by date.

    The API does not provide transcripts, recording downloads or login details for connected services.

    Revoke a key

    1. Open Integrations, then For developers, then Manage API keys, as an owner or admin.
    2. Find the key you want to stop using and press Revoke. There is no confirmation dialogue.
    3. Check the retained row for Revoked. The key stops working.

    Revoking a key also stops any webhook subscriptions it created.

    If something fails

    If the list says We couldn't load your API keys, refresh the page or contact support if the problem continues. If creating or revoking a key fails, try again.

    An API request can fail if the key is invalid or lacks the required permission. If the response says Too many requests. Wait a minute and try again., wait before retrying. Other temporary errors ask you to try again shortly.

    Questions this raises

    Not seeing your question? Ask us directly on a demo.

    Can I recover a lost key?

    No. The full key is shown only once, when created. If you lose it, create another.

    Can a key change receptionist settings or create bookings?

    No. It cannot change receptionist settings or create calls or bookings. Every key can read data.

    Why has Last used not changed yet?

    Usage dates update about once a minute, so they may not change after each request.

    Can support see my keys here?

    No. The support view hides keys. Only your own team can see the list.

    Still not sure? Show us your setup.

    Twenty minutes, your actual number and provider, and a straight answer about what to do.

    Test Ringar AI