Authentication

The two credential planes — grp_sk_ management keys and grp_at_ read-only access tokens — and how bearer auth works.

Every request to the Grepticon API carries a bearer credential:

Authorization: Bearer grp_sk_your_key_here

There are exactly two kinds of credential, and the prefix tells them apart. A grp_sk_ management key controls an account; a grp_at_ access token is a read-only, single-workspace credential you mint from a key. Which one you send decides what the request is allowed to do — nothing else about the request matters for authorization.

Management keys (`grp_sk_`)

A management key is the account plane. It authenticates your automation the way a password would, and it can do everything: create and delete workspaces, upload and delete files, mint and revoke access tokens, and read audit logs.

Created in the console. Open API Keys at /keys and click Create key.
Shown exactly once. The full grp_sk_… secret is displayed only at creation — copy it then. Grepticon stores only a hash, so a lost key can't be recovered; revoke it and create another.
This is what the SDK authenticates with. new GrepticonClient({ apiKey }) takes your grp_sk_ key.

Treat a management key like any production secret: keep it in an environment variable or secret manager, never in client-side code, and rotate it by creating a replacement and revoking the old one.

A management key sees every file in the account, regardless of visibility tags. Never hand a grp_sk_ key to an agent — mint a scoped access token instead.

Access tokens (`grp_at_`)

An access token is the agent read surface. You mint one from a management key, scoped to a single workspace, and it is read-only by construction: the management routes reject it. Any attempt to create a workspace, upload a file, or mint another token with an access token returns 403 with a fixed message — "Access tokens are read-only. Use a management key (grp_sk) for this operation."_

Access tokens are how you give an agent exactly the reach it needs:

One workspace. A token is bound to the workspace it was minted against.
Carries claims. The token stores the claims you mint it with, and those claims decide which files it can see. See Access control.
Time-boxed. ttlSeconds defaults to 1 hour and is clamped between 1 minute and 24 hours. Mint a fresh token per agent session.
Revocable immediately. Revoking a token takes effect on the next request.

Mint and revoke tokens through the SDK (or the REST /tokens route):

import { GrepticonClient } from '@grepticon/sdk';

const client = new GrepticonClient({ apiKey: process.env.GREPTICON_API_KEY ?? '' });

// Default claims (['*']) see every file in the workspace.
const { token } = await client.tokens.mint('handbook', { ttlSeconds: 600 });

client.session(ws) reads with the credential the client was built with — not with a token you just minted. To read as a scoped token, construct a second client keyed by that token: new GrepticonClient({ apiKey: token }).session(ws). The Quickstart shows this pattern in full.

The two credentials at a glance

	`grp_sk_` management key	`grp_at_` access token
Plane	Account	Single workspace
Access	Full CRUD + reads	Reads only (403 on writes)
Sees	Every file in the account	Files its claims permit
Created via	Console at `/keys` (shown once)	`tokens.mint` from a key
Lifetime	Until revoked	TTL 1 min – 24 h, or revoked
Give to an agent?	Never	Yes

Where to go next

Access control — how a token's claims and a file's visibility decide what a read can see.
SDK reference — the full tokens.mint / tokens.revoke surface.
Tokens API — the REST wire format for minting and revoking.

Management keys (grp_sk_)

Access tokens (grp_at_)

The two credentials at a glance

Where to go next

On this page

Management keys (`grp_sk_`)

Access tokens (`grp_at_`)