---
title: "Manage API keys as an administrator"
description: "Administrators create and revoke Talkspirit API keys in Administration, choose the scopes each key carries, and copy the key value once"
category: integrations
section: api-and-webhooks
tags: [admin]
type: Tutorial
lastUpdated: 2026-11-13
locale: en
canonical: https://support.talkspirit.com/en/integrations/manage-api-tokens-as-an-admin
---

# Manage API keys as an administrator


An API key lets a partner integration call the Talkspirit REST API on behalf of one member of your organisation. Administrators create and revoke keys in **Administration**, under **Security** then **API**.

> **In summary:** open **Administration**, then **API**, click **Create API key**, name the partner, choose the member the key acts as, tick the scopes it needs, and copy the key. It appears once and cannot be shown again.

The Talkspirit API is a partner surface, not a general-purpose public API. Each key is minted for one named partner, there is no self-service developer portal, and the resources a key reaches are deliberately narrow: members, circles, roles, tensions, working agreements, meetings, goals, projects and tasks.

## Before you start

You need three things.

- **Administrator rights.** Talkspirit rejects key creation and revocation from anyone else.
- **The API module, switched on for your organisation.** It is off by default. Without it, **API** does not appear in the Administration menu, and opening the page by its address returns a not-found page. Ask your Talkspirit contact to enable it.
- **The partner's account, already in your organisation.** A key acts as one member, and Talkspirit provisions a dedicated account for each partner. Ask your Talkspirit contact to create that account before you mint a key for it.

## Create an API key

1. Go to **Administration**, then **API** under **Security**.
2. Click **Create API key**.
3. Enter the **Partner name**. It identifies the key in the list, so name the partner rather than the purpose.
4. In **Owner**, search for the member the key acts as and select them. The key sees exactly what that member sees, and nothing more.
5. Under **Access**, pick a starting point: **Read-only** (selected when the dialog opens), **Read and write**, or **Custom**. The matrix below lists one resource per row, with **Read**, **Write** and **Delete** columns, and its ticks follow the starting point. Untick what the integration does not need and tick what it must have. Ticking a **Write** also ticks the **Read** of the same resource, and any tick you change yourself switches the starting point to **Custom**. Check the matrix before you continue: it includes writes, and it includes **Delete tensions**, which deletes permanently. At least one scope is required.
6. Click **Create API key**.
7. Copy the key, store it in your password manager, then click **Close**.

![The API page in Talkspirit Administration. API is highlighted in the Security section of the Administration menu, the Create API key button sits at the top right, and the page reads "No API keys yet".](/images/integrations/manage-api-tokens-as-an-admin/01-administration-api-page.png)

> **Warning:** the key starts with `ts_partner_` and is shown once, at creation. Talkspirit keeps only a hashed copy, so nobody can display it again. If you lose it, revoke the key and create another.

## What each scope allows

Scopes decide what the key can reach. Twenty-four exist. The dialog lays them out as a matrix, one row per resource, grouped by the module the resource reads from, because a scope is only offered when that module is active on your organisation. Four are ungated and always offered, under **Administration**; the rest need Structure, Goals, Projects or Meetings.

The starting points tick these scopes for you. **Read-only** ticks the reads each module shares and nothing else. It leaves out nine reads that reach further, which take a deliberate tick: **Read users**, **Read working agreements**, **Read the audit log**, **Read the activity history** and the five exports (**Users export**, **Organisation export**, **Checklists and metrics export**, **Goals export** and **Tasks and projects export**). **Read and write** adds writing wherever the read is ticked (circles, roles, tensions, tasks and meetings), and never deletes. **Custom** is whatever you tick yourself.

The scope names follow your organisation's own vocabulary, so if you renamed circles or roles in **Terminology**, the checkboxes use your words.

| Group | Scope | What a key carrying it can do |
| --- | --- | --- |
| Always offered | **Read users** (`users:read`) | Read members and their memberships |
| Always offered | **Write users** (`users:write`) | Edit members, and set custom-field values on them |
| Always offered | **Read the audit log** (`audit_log:read`) | Read the organisation's activity log. The key's owner must also be an administrator, otherwise the route refuses the call |
| Always offered | **Users export** (`user_export:read`) | Start an export of all members and download its file: one CSV file, one row per member, with name, e-mail address, role, status, profile fields and last connection. It is the **Users export** row of the matrix, in the **Read** column. The key's owner must be an administrator of the organisation, otherwise the route refuses the call |
| Structure | **Read circles** (`circles:read`) | Read circles and their members |
| Structure | **Write circles** (`circles:write`) | Set custom-field values on a circle |
| Structure | **Read roles** (`roles:read`) | Read roles and their members |
| Structure | **Write roles** (`roles:write`) | Set custom-field values on a role |
| Structure | **Read tensions** (`tensions:read`) | Read tensions |
| Structure | **Write tensions** (`tensions:write`) | Create and edit tensions, and change their status |
| Structure | **Write tensions on behalf of a member** (`tensions:write_on_behalf`) | Name a member as the creator when creating a tension, so that the tension is theirs. It has a row of its own in the matrix, and **Write tensions** does not include it |
| Structure | **Delete tensions** (`tensions:delete`) | **Delete tensions permanently.** See the warning below |
| Structure | **Read working agreements** (`documents:read`) | Read working agreements, their text and their comments |
| Structure | **Organisation export** (`structure_export:read`) | Start an export of the organisation and download its file: the circles, roles and who holds what, with each holder's e-mail address, as an Excel workbook or CSV files. It is the **Organisation export** row of the matrix, in the **Read** column, with the note “Requires the key's account to be an administrator”: the key's owner must be an administrator of the organisation, otherwise the route refuses the call |
| Structure | **Checklists and metrics export** (`checklist_metric_export:read`) | Start an export of the organisation's checklists and metrics and download its Excel workbook: each item with its circle or role, status, recurrence, last check and assignees. The key's owner must be an administrator of the organisation, otherwise the route refuses the call |
| Structure | **Read the activity history** (`activity:read`) | Read who was seated on or removed from a role, or added to or removed from a circle, who made the change and when. It is off unless you tick it, and the **Read-only** starting point leaves it out. It needs no administrator role: the key sees what its owner sees. Not to be confused with the activity log that **Read the audit log** opens |
| Goals | **Read goals** (`goals:read`) | Read goals, their key results, their comments and time periods |
| Goals | **Goals export** (`goal_export:read`) | Start an export of the goals and their key results and download its Excel workbook, with a Goals sheet and a Key results sheet. Private goals are in it only while your organisation's admin oversight is on. The key's owner must be an administrator of the organisation, otherwise the route refuses the call |
| Projects | **Read projects** (`projects:read`) | Read projects and their comments, sections and labels |
| Projects | **Read tasks** (`tasks:read`) | Read the tasks the owner can see, and their comments |
| Projects | **Write tasks** (`tasks:write`) | Create tasks, as the owner |
| Projects | **Tasks and projects export** (`task_export:read`) | Start an export of the tasks and projects and download its Excel workbook, with a Tasks sheet and a Projects sheet. Private projects and their tasks are in it only while your organisation's admin oversight is on. The key's owner must be an administrator of the organisation, otherwise the route refuses the call |
| Meetings | **Read meetings** (`meetings:read`) | Read the meetings the owner can see |
| Meetings | **Write meetings** (`meetings:write`) | Add an item to the agenda of a meeting the owner can see. Give it together with **Read meetings**, so the integration can check what it wrote |

Sixteen of the twenty-four only read. The other eight change your organisation's data, so grant them only to an integration that has to write, and protect such a key as carefully as a password.

> **Warning:** **Delete tensions** is destructive and cannot be undone. A key carrying it deletes tensions permanently, with no recovery. It is deliberately separate from **Write tensions**, which does not include it, so grant it only when an integration genuinely has to clean up after itself. It reaches only the tensions the key's own account created.

Whatever you tick, a key never reaches more than its owner does. If a partner must read every member of the organisation, the owner account needs that visibility first.

## Revoke an API key

1. On the **API** page, open the actions menu at the end of the key's row.
2. Click **Revoke**.
3. Confirm with **Revoke**.

Revocation takes effect at once and cannot be undone. The key stays in the list with the status **Revoked**, so you keep the record of what existed. Keys have no expiry date: one works until you revoke it, or until the API module is switched off for your organisation, which stops every key at the same time.

## What's next?

- [Talkspirit API Documentation](/en/integrations/partner-api)
- [Turning an integration on or off](/en/integrations/enable-a-cloud-file-picker)
