Team & platform

Create and revoke API keys

Account → API keys. An API key lets your own code, scripts and tools call the VeraGen API for this account, without anyone signing in. Only an owner or an admin can see this page and create or revoke keys.

What a key can do

A key belongs to the account, not to the person who created it: it keeps working if that person leaves the team, and the page shows who created each one. It can reach everything in the account that its scopes allow, in every project, the same as an owner or admin. The endpoints and how to call them are in the VeraGen API documentation.

Read only gives a key every read scope and nothing else: it can never change your data or spend credit. Read and write gives it every scope. Custom lets you tick exactly the ones it needs. A scope with no endpoint yet is accepted, so a key made today keeps working as endpoints are added.

Today a key can:

• List and read automations (automations:read): every automation in Tellagent, in every project, with its status, what starts it, a summary of its steps (how many, which kinds, whether it sends email, texts or team notifications) and how many contacts it has run for. The steps' settings, such as addresses, message text and webhook addresses, are never included. It also lists an automation's runs, the same rows as Run history, and reads one run with each step it has run.
• Enroll contacts in an automation (automations:enroll): the same as Enroll contacts in the hub, up to 500 contacts at a time, and only in a published automation (a draft or a paused one refuses). Enrolling sends real messages: each contact's run starts within about a minute and sends the automation's emails, and its texts where texting is set up. Run history shows the run as Enrolled through the API by key with the key's name and its first characters, and the audit log records which key enrolled them. A contact who is not in the account or is archived, or who was erased from Thrive at their request, is skipped, and so is one already in the automation or past its re-entry rule. A contact on do-not-contact, or who opted out of email or unsubscribed, is enrolled as in the hub, but every email step skips them and says why in the run; they get no texts if they are on do-not-contact, replied STOP or have not agreed to texts. Each request needs an Idempotency-Key, so a retry never enrolls anyone twice. The API cannot create, change, publish or pause an automation.
• List and read workflows (workflows:read): every workflow in the account, each with its latest run.
• Start a workflow run (workflows:run): the run is queued and begins within about a minute, with up to two minutes to finish, like a run started with Background in the editor. It appears in the workflow's run history like any other run, and the account's audit log records which key started it.
• Follow runs (workflows:read): a workflow's runs, however they were started, and each run's status, its blocks and what it was billed.
• Read usage (usage:read): what the account was billed, per day and per feature, and its balance.
• List projects and read Data Management (content:read): the account's projects, the items in a project (filtered by kind, folder or name), and any item's details. For a page that includes its text; files, datasets, images and links come back as their details only.
• Create a page (content:write): a new page in a project, at the top of the project or in a folder, from Markdown or HTML. It is cleaned exactly as a page saved in the hub is, so scripts and anything else a page cannot hold are removed. It appears in Data Management like any other page, with a first version in its history that names the key, and the account's audit log records which key created it. It is indexed for search like any page, and that indexing is billed as it is for any page.

• List and read Thrive contacts (contacts:read): every contact in the account, newest first, searched by name, email, title or company, or found by exact email address, lifecycle stage, or changed since a given time (useful for keeping another system in step). Deleted contacts are left out.
• Create and update Thrive contacts (contacts:write): a new contact needs a name. It is unassigned: owners and admins see it in Thrive under Unassigned and can assign it; its activity says it was created by the key, and the account's audit log records which key created or changed it. An update changes only the fields it sends, and leaves the rest as they are.

• Read Skunk Works (skunkworks:read): the account's projects that have opened Skunk Works, each with its key prefix and how many items, epics and open sprints it has; a project's work items, most recently changed first, filtered by status, type, sprint, assignee (by email), epic, label, a key or words in the title or description, or changed since a given time; one item by its key, with its description, the Data Management documents linked to it and its whole history, comments included; and a project's sprints with their dates, goal, items and points, and a finished sprint's review. It is read-only: items cannot be created or changed through the API, and reading never turns on Skunk Works in a project that has not used it.

What the API will not do with contacts:

• No second contact for the same email address. If a contact already has the address, nothing is created or changed, and the API answers with that contact's id so your code can update it instead.
• It never lifts a do-not-contact or an email opt-out. A key can mark someone as opted out of email, but only a person in Thrive can opt them back in. Someone erased from Thrive at their request cannot be added again or changed through the API.
• It does not delete contacts, and the contacts endpoints do not send email or anything else to them. Only enrolling a contact in an automation (automations:enroll) sends them anything.

Files cannot be uploaded or downloaded through the API, and pages cannot be changed or deleted through it yet. Companies and deals in Thrive are not available through the API yet.

What a run started by a key spends

A run started with a key spends the account's AI credit, the same as any other run: it shows on Billing and Observability under Tellagent. It is the account's spend, not any member's, so it does not count toward a member's own monthly cap. It reaches everything in the account the key can, so a workflow that writes a page into a project does so even if the person who built the workflow is not in that project.

• If the account is out of credit, the API refuses to start the run.
• A monthly spend cap on a key stops its runs once they have been billed that much in a calendar month (UTC): a run that reaches the cap stops part way, and new runs are refused until the month turns or the cap is raised. A key without a cap is limited only by the account's credit.
• An account can start a limited number of runs through the API each minute, and have a limited number queued or running at once; the API says so when a limit is reached.
• If a key is revoked after it started a run but before the run began, the run does not start, and its history says why.

Create a key

1. Go to Account → API keys and click Create key.
2. Give it a Name that says what will use it, such as "Zapier production". One key per system means you can revoke one without stopping the others.
3. Choose Read only, Read and write or Custom scopes.
4. Optionally set Expires: the key stops working at the end of that day (UTC). Leave it empty for a key that works until you revoke it.
5. Optionally set a Monthly spend cap in US dollars, for a key that can start runs. Leave it empty for no cap.
6. Click Create key, then Copy the key.

A key starts with vg_live_. The list shows only its first characters, what its runs have been billed this month (and its cap, if it has one), when it was created and by whom, and when it was last used (updated every few minutes). An account can have up to 10 active keys.

To change a key's cap later, click Cap beside it, enter the new amount (or clear it for no cap) and click Save.

Keep keys secret

• Send a key only from a server or a script you control, as Authorization: Bearer vg_live_…. Never put it in a web page or a mobile app, where anyone can read it: the API does not accept calls from browsers.
• Store it in a password manager or your server's secrets, not in source code.

Revoke a key

Click Revoke beside the key and confirm. Anything using it stops working on its next request. A revoked key stays in the list, marked Revoked, so you can see when it was revoked; it cannot be turned back on.

Every key creation, change and revocation is recorded with who did it and when.