Authentication

Tauth uses two ways to authenticate: JWT bearer tokens for interactive users and API keys for machine-to-machine access.

JWT tokens

Register

POST /auth/register
Content-Type: application/json

{
  "email": "alice@example.com",
  "password": "hunter2",
  "org_name": "Acme Media"
}

Returns:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

Login

POST /auth/login
Content-Type: application/json

{
  "email": "alice@example.com",
  "password": "hunter2"
}

Refresh

Access tokens expire after 15 minutes. Use the refresh token (valid for 30 days) to obtain a new pair:

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

Using a token

Include the access token as a Bearer header on every authenticated request:

Authorization: Bearer eyJ...

Get current user

GET /auth/me
Authorization: Bearer eyJ...

{
  "user_id": "uuid",
  "email": "alice@example.com",
  "org_id": "uuid",
  "role": "admin"
}

Roles

Role	Permissions
admin	Upload, sign, verify, manage org users and API keys
signer	Upload and sign files
viewer	Verify files only

API keys

API keys are scoped to your organisation and useful for CI/CD pipelines or server-side integrations.

Create an API key

POST /org/api-keys
Authorization: Bearer eyJ...
Content-Type: application/json

{ "name": "ci-pipeline" }

{
  "key_id": "uuid",
  "name": "ci-pipeline",
  "key": "tauth_sk_live_xxxxxxxxxxxx"
}

WARNING

The raw key is returned once only. Store it securely. Tauth never displays it again.

Use an API key

Pass it in the X-API-Key header:

X-API-Key: tauth_sk_live_xxxxxxxxxxxx

Revoke an API key

DELETE /org/api-keys/{key_id}
Authorization: Bearer eyJ...

Token storage

The web app stores tokens in localStorage under the keys tauth_access_token and tauth_refresh_token. For production deployments consider using httpOnly cookies to mitigate XSS risk.