GETTING STARTED

Authentication

Tesska has three authentication planes: console accounts for humans, project API keys for your server-side code, and Connect Tesska OAuth for third-party apps acting on behalf of a user. This page draws the boundaries between them and covers how to handle your keys.

Three authentication planes

Before calling anything, be clear about which identity you are using:

Console account — email + password sign-in on tesska.com, for managing the vault, grants, and approvals. For humans, never for code.
Project API key — a tsk_-prefixed Bearer key issued in the console Token Center, scoped to one project, for your server-side code.
Connect Tesska OAuth — a per-user access_token obtained by third-party apps via authorization code + PKCE, usable directly as a Bearer on /v1/*.

Console accounts

Sign up and sign in with email + password; forgotten passwords are reset via email. The console is the home for every human operation:

Store, freeze, and revoke credentials
Issue and revoke project keys in the Token Center
Approve consent-mode (B) call requests
Manage Connected Apps and Developer Apps

API requests never use your email and password./v1/* only accepts Bearer keys. A compromised console password does not expose your API surface, and a leaked key cannot touch your console.

Project API keys (Bearer)

Issue a key per project in the Token Center. The key itself contains no credentials — what it can exchange for is defined entirely by project × credential × scope grants, which you can narrow at any time or revoke with one click. Every /v1/* endpoint authenticates with it as a Bearer:

Each grant = project × credential × scope, with its own token TTL cap and per-minute rate limit
Per-project platform allowlist: a key can only reach platforms on the list
Revocation takes effect immediately; the full audit trail records metadata only, never plaintext

# All /v1/* endpoints take a project key as Bearer
# Issued in Console -> Token Center, prefix "tsk_"
export TESSKA_KEY="tsk_..."

# List the grants this key can use
curl https://tesska.com/v1/grants \
  -H "Authorization: Bearer $TESSKA_KEY"

# Exchange a grant for a short-lived access token
curl -X POST https://tesska.com/v1/login \
  -H "Authorization: Bearer $TESSKA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "github", "account": "deploy-bot", "scope": ["repo:read"]}'

Connect Tesska (OAuth)

If you are building a third-party app for Tesska users, never ask them to hand over a project key — use Connect Tesska instead: GET /oauth/authorize (authorization code with mandatory PKCE S256; parameters client_id / redirect_uri / state / code_challenge) → user consent page → POST /oauth/token exchanges code + code_verifier for an access_token.

The access_token is a per-user, revocable, scoped key you can use directly as a Bearer on /v1/*
Register your client self-serve under Developer Apps in the console; the client_secret is shown only once
Users can withdraw access at any time with one click under Connected Apps

Key handling best practices

Inject keys via environment variables or a secret manager — never commit them to the repo, including sample code, test fixtures, and frontend bundles
Use a separate key per project and per environment, so you can narrow scopes minimally and revoke independently
If you suspect a leak, revoke first and investigate second: one click in the Token Center takes effect immediately, then issue a fresh key
Periodically audit what a key can reach with GET /v1/grants and drop grants you no longer use

A leaked key cannot yield your original credentials.Under the default delivery, a project key only exchanges for short-lived access tokens; raw secret delivery requires an explicit per-asset setting plus a global switch (off by default). Combined with instant revocation and full auditing, the blast radius stays minimal.

Official SDKsNot yet released

Official SDKs have not shipped yet. The API is plain HTTPS + JSON: any HTTP client (curl, fetch, requests, …) works with the Authorization header shown above, and every docs page includes copy-paste examples.