---
title: "Core concepts"
description: "Organization, workspace, library, workspace key, API key and role, in plain words."
---

> Documentation Index
> Fetch the complete documentation index at: https://tarkle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Core concepts

A few words come up on every page of these docs. The API key is the one credential you send with each call.

| Term | Meaning |
| --- | --- |
| **Organization** | The account that owns the plan and the workspaces. |
| **Workspace** | A place where a team keeps its files, contacts, branding and members. A workspace has no plan of its own: the organization's plan sets how many workspaces it can have. |
| **Workspace key** | The 8-character code that names a workspace in the API. `GET /api/v1/workspaces` lists the keys you can use. |
| **Library** | The files and folders of a workspace. Some folders are protected (File requests, team folders, transfer folders) and the API cannot change them. |
| **API key** | The secret that proves who is calling. It reaches the workspaces chosen when it was made and acts as the person who made it. See [API keys](/docs/get-started/api-keys). |
| **Role** | What a person may do in a workspace: owner, admin, member or viewer. An API key is checked against the role of its creator. |
| **Problem document** | The JSON shape of every API error, with a `code` to match on. See [Errors](/docs/api/errors). |

## The API key

An API key is the one credential for the Tarkle API and the MCP server. Only an owner or admin of the organization can open Settings, API and make keys there. The **API keys** tab lists every key of the organization. A key has a name and an access choice: **All workspaces**, or **Only selected workspaces** with the workspaces you tick. A key does not expire, and deleting it stops it at once.

A key does everything the API and the MCP server can do, read and write, in the workspaces it reaches. It acts as the person who made it. The one thing no API key can do is make a purchase.

The key is shown once, when it is created. An owner or admin can copy it again from the row menu with **Copy token**. **Rename** and **Delete** are in the same menu. Keys made before full access existed keep working with the permissions they were given. They carry a **Legacy** badge and their **Copy token** is not available. The MCP server does not accept them, so create a new key to get the full set.

## Which workspaces a key reaches

A key with **All workspaces** reaches every workspace of the organization. A key with selected workspaces reaches only those, does not list the others, and gets `403` with the code `no_access` for any other workspace. An unknown workspace key gets the same answer, so a key cannot be used to find out which workspaces exist.

## How a call is checked

A call sends the key as `Authorization: Bearer <your-tarkle-key>` and names its workspace with the `X-Workspace-Key` header, the 8-character workspace key. Tarkle checks the call in this order:

1. The key is valid and not deleted. Otherwise the answer is `401` with `unauthorized`.
2. The key holds the permission the endpoint needs. Otherwise the answer is `403` with `forbidden`. A Legacy key may lack some permissions.
3. The call names the workspace by its workspace key. Sending the workspace id instead gets `400` with `workspace_key_required`.
4. The key reaches that workspace. Otherwise the answer is `403` with `no_access`.
5. The creator still has access to that workspace. Brand endpoints also need the creator to be an owner or admin of it. If the creator loses access, the key loses it too.

## MCP server

Coding assistants and other clients that send a header use the key as `Authorization: Bearer <your-tarkle-key>` on `https://mcp.tarkle.com/mcp`. A client that signs in through the browser needs no key. The MCP server works with the same workspace reach as the key it was given.

## Where to go next

- [Quickstart](/docs/get-started/quickstart)
- [Authentication](/docs/get-started/authentication): how to send the key with each request.
- [API keys](/docs/get-started/api-keys): create, copy, rename and delete keys.
- [Product areas](/docs/products): what each part of Tarkle is and what the API covers today.
- [API reference](/docs/api)

Source: https://tarkle.com/docs/get-started/concepts/index.mdx