--- 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-09-11 locale: en canonical: https://support.talkspirit.com/en/integrations/manage-api-tokens-as-an-admin --- # Manage API keys as an administrator ## 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 **Scopes**, tick what the key is allowed to do. Every scope your organisation can grant is already ticked when the dialog opens, so **untick everything the integration does not need**, and check the list 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. Sixteen exist, and the dialog groups them by the module they read from, because a scope is only offered when that module is active on your organisation. Three are ungated and always offered; the rest need Structure, Goals, Projects or Meetings. 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`) | Nothing today. It is reserved: no endpoint requires it yet | | 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 | **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 | | Goals | **Read goals** (`goals:read`) | Read goals, their key results, their comments and time periods | | 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 | | Meetings | **Read meetings** (`meetings:read`) | Read the meetings the owner can see | Ten of the sixteen only read. The other six 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](/integrations/partner-api) - [Turning an integration on or off](/integrations/enable-a-cloud-file-picker)