---
title: "Tarkle auth.md"
description: "How an AI agent authenticates with Tarkle: what is supported, what is not, and where a person has to act."
canonical: "https://tarkle.com/auth.md"
last-updated: 2026-11-04
---

# auth.md

You are an agent. This is how you authenticate with Tarkle. Tarkle does not offer agentic registration: you cannot create an account, a token or an identity for a user. A person signs in to Tarkle, creates an API token and gives it to you. Follow the steps in order.

## Step 1: Discover

A request to the API without a valid token answers 401 and says where the protected resource metadata is (RFC 9728):

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://tarkle.com/.well-known/oauth-protected-resource/api/v1"
Content-Type: application/problem+json
```

Fetch `https://tarkle.com/.well-known/oauth-protected-resource/api/v1`. It lists the resource (`https://tarkle.com/api/v1`), the scopes (`scopes_supported`), the way to send the token (`bearer_methods_supported`: `header`) and the documentation. It has no `authorization_servers`: there is no OAuth server for this API, so there is no `/.well-known/oauth-authorization-server` for it and no `agent_auth` block.

The API description needs no token: https://tarkle.com/api/v1/openapi.json

## Step 2: Pick a method

One method works for the public API: a personal API token (`tk_...`) that a person creates in the app. The agent registration types are not supported:

- `identity_assertion` with `id-jag`: not supported.
- `service_auth` (registration from a user email): not supported.
- `anonymous`: not supported.

## Step 3: Register

There is no `identity_endpoint`: `POST /agent/identity` does not exist. Ask the user to do this once:

1. Sign in at https://tarkle.com/sign-in.
2. Open Settings, API, and choose New token.
3. Pick the scopes the agent needs (for example `brands:read`) and copy the token. It is shown once.

Before the user hands the token over, tell them which scopes you need and why. The scope `billing:purchase` lets you buy a lifetime plan for the user's organization with a payment token the user grants in the Link app. Ask for it only for that. Live payments are not open yet (503 `agentic_commerce_not_enabled`).

## Step 4: Claim

Not needed. A token belongs to the person who created it, so there is no claim ceremony and no user code. Ask the user to put the token in an environment variable on a server. Do not put it in a browser and do not ask them to paste it into a chat you do not control.

## Step 5: Exchange

Not needed. The token is the credential: there is no `identity_assertion` to exchange and no token endpoint. It does not expire unless the user set an end date, and there is no refresh token.

## Step 6: Use the access_token

Send it on every request:

```http
GET https://tarkle.com/api/v1/workspaces
Authorization: Bearer tk_...
```

- A token works for every workspace its creator can use. `GET /workspaces` lists them with an 8-character `workspace_key`.
- Every call inside a workspace also sends `X-Workspace-Key: <workspace_key>`.
- Read `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` on every response. A 429 carries `Retry-After` in seconds.
- Full reference: https://tarkle.com/docs/api

## Errors

Errors are RFC 9457 problem details (`application/problem+json`) with a stable `code`. Every code is explained at https://tarkle.com/docs/api/errors

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `unauthorized` | The token is missing, invalid or revoked. Ask the user for a new one. The `WWW-Authenticate` header points at the metadata in Step 1. |
| 401 | `legacy_token` | An older workspace token that no longer works. Ask the user for a new token. |
| 403 | `token_without_scope`, `no_access`, `forbidden` | The token lacks the scope or the workspace. Ask the user for a token with the scope. Do not retry. |
| 429 | `rate_limited` | Wait `Retry-After` seconds, then retry. |
| 5xx | `unavailable` and others | Retry with exponential backoff. |

## Revocation

There is no revocation endpoint and no agent-initiated revocation. The user deletes the token in Settings, API, and it stops working at once. After a 401 on a token that worked, ask the user for a new one.

## MCP server

The MCP endpoint is https://mcp.tarkle.com/mcp. A client that supports OAuth discovers sign-in from https://mcp.tarkle.com/.well-known/oauth-protected-resource/mcp and opens the browser for the user. A personal access token can be sent as `Authorization: Bearer ...` instead.

## What needs a person

Creating an account, buying a plan and creating a token are done by the user in the Tarkle app. Everything after that can be done by the agent with the token.

Contact: https://tarkle.com/contact