---
title: "Control API authentication | Tarka Docs"
description: "Authenticate Tarka Control API REST and gRPC requests and understand account, membership, role, entitlement, and API-key boundaries."
url: "https://tarkahq.com/docs/control-api/authentication/"
---

Available Control API · Authentication

# Authentication and authorization

A valid bearer proves identity; account approval, organization membership, role, product entitlement, and key scope decide what that identity may do.

Account token

## Use the signed-in Tarka account session

The ordinary Control API credential is the short-lived access token issued by Tarka account authentication. The console uses this same token. Refresh it through the account session before it expires.

REST `Authorization header`

```
curl "https://tarka.rest/control/v1/me" \
  -H "Authorization: Bearer $TARKA_ACCOUNT_TOKEN"
```

gRPC `metadata`

```
grpcurl \
  -H "authorization: Bearer $TARKA_ACCOUNT_TOKEN" \
  grpc.tarka.rest:443 \
  tarka.provisioning.v1.ProvisioningService/GetCurrentUser
```

**Working outside the browser?**

The console keeps your session in HTTP-only cookies, so its token cannot be copied out, and there is no command-line sign-in. To work from an AI assistant, connect it through [MCP](https://tarkahq.com/docs/control-api/mcp/): it signs in with your account and calls the Control API's methods as tools. For inference, utility models, and Code Sandboxes, use a `tk_live_` key with the matching scope.

**Keep account tokens server-side.**

Do not put a Tarka account token in a public browser bundle, repository, image, log, or shared shell history. It carries the account's current organization roles.

Credential boundary

## Use each credential only on its intended plane

| Credential | Accepted by | Not accepted by |
| --- | --- | --- |
| **Account access token** | Every Control API REST and gRPC method | Inference runtime requests |
| **MCP connection** | `https://tarka.rest/mcp`, within its read or write access | Control API REST and gRPC, and inference |
| **`tk_live_` + inference** | Language-model runtime routes | Ordinary Control API methods |
| **`tk_live_` + utilities** | OCR, transcription, translation, and speech routes | Ordinary Control API methods |
| **`tk_live_` + sandboxes** | SandboxService methods for the key's organization | Other Control API methods and other organizations |
| **S3 access key pair** | `storage.tarka.rest` for one bucket | Tarka REST, gRPC, and Hosted Git |
| **SSH key or Git PAT** | `git.tarka.rest` | Control, inference, and object-storage APIs |

Authorization

## Five checks protect workspace state

A valid token alone does not authorize a resource operation.

1. 01

   **Platform access**

   The account's platform entitlement must be approved rather than pending, suspended, or revoked.
2. 02

   **Organization state**

   The requested organization and membership must both be active.
3. 03

   **Organization role**

   The role must permit the requested read or mutation.
4. 04

   **Product entitlement**

   Each product requires an approved product entitlement.
5. 05

   **API-key scope**

   When SandboxService is called with `tk_live_`, the key must be active, organization-bound, and include `sandboxes`.

Roles

## Organization role matrix

Product entitlements can still deny an operation that the role would otherwise permit.

| Ability | Owner | Admin | Operator | Member | Viewer |
| --- | --- | --- | --- | --- | --- |
| Read organization, members, models, usage, resources, and product state | Yes | Yes | Yes | Yes | Yes |
| Submit a product-access request | Yes | Yes | Yes | Yes | Yes |
| Rename organization or replace quota policy | Yes | Yes | No | No | No |
| Create or revoke API keys | Yes | Yes | Yes | No | No |
| Mutate compute, sandbox, storage, or repository resources | Yes | Yes | Yes | No | No |

Not Control API methods

## Account lifecycle remains with Tarka Auth

Signup, email verification, login, password recovery, session refresh, and logout are identity-provider flows at [the Tarka account surface](https://tarkahq.com/console/). Operator approval is an internal administration workflow. Neither is represented as a customer provisioning RPC.

**Start with `GET /me`.**

A `200` response confirms token validity and platform approval while returning usable organization IDs. A `403` such as `account_pending` is an access decision, not a token-refresh signal.