Authentication

Truthlock supports multiple authentication methods to secure API access. This guide covers API keys, JWT tokens, and security best practices.

Authentication Methods

API Keys

Long-lived credentials for server-to-server communication. Recommended for backend services.

Bearer Tokens (JWT)

Short-lived tokens for authenticated users. Ideal for frontend applications and user context.

API Keys

API keys are the primary authentication method for Truthlock. They are scoped to a tenant and can have fine-grained permissions.

Using API Keys

Include your API key in the X-API-Key header:

curl -X GET https://api.truthlocks.com/v1/issuers \
  -H "X-API-Key: tl_live_your_api_key"

Key Structure

tl_live_abc123def456gh789ijklmnopqrstuv
│  │    │
│  │    └── 32-character random identifier
│  └── Environment: dev | live
└── Prefix: tl (Truthlock)

Scopes

API keys can be restricted to specific permissions:

Scope	Permissions
`attestations:mint`	Create new attestations
`attestations:read`	Read attestation details and proof bundles
`attestations:revoke`	Revoke attestations
`issuers:read`	View issuer information
`issuers:write`	Create and manage issuers
`users:read`	View users and roles
`users:write`	Invite users, manage roles
`audit:read`	Query audit logs

Principle of Least Privilege: Only grant the scopes your application actually needs. A key with attestations:mintonly should not also have users:write.

Creating API Keys

Via Console

Navigate to console.truthlocks.com/api-keys
Click "Create API Key"
Enter a descriptive name (e.g., "Production Backend")
Select the required scopes
Copy the key immediately — it won't be shown again

Via API

curl -X POST https://api.truthlocks.com/v1/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Backend",
    "scopes": ["attestations:mint", "attestations:read", "issuers:read"]
  }'

Response

{
  "id": "key-uuid",
  "name": "Production Backend",
  "prefix": "tl_live_abc",
  "secret": "tl_live_abc123def456gh789ijklmnopqrstuv",
  "scopes": ["attestations:mint", "attestations:read", "issuers:read"],
  "created_at": "2026-01-13T12:00:00Z"
}

Critical: The secret field is only returned once at creation time. Store it immediately in a secrets manager.

Bearer Tokens (JWT)

JWT tokens are used when you need to make API calls on behalf of an authenticated user, such as from a web or mobile application.

Using Bearer Tokens

curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Structure

{
  "sub": "user-uuid",
  "tenant_id": "tenant-uuid",
  "email": "user@example.com",
  "roles": ["admin"],
  "iat": 1705147200,
  "exp": 1705150800,
  "iss": "https://auth.truthlocks.com"
}

Token Lifetime

Token Type	Lifetime	Refresh
Access Token	1 hour	Via refresh token
Refresh Token	30 days	Via re-authentication

Security Best Practices

✅ Use Secrets Management

Store API keys in AWS Secrets Manager, HashiCorp Vault, or similar. Never hardcode keys in application code.

✅ Rotate Keys Regularly

Create new keys and revoke old ones periodically. Use descriptive names with dates (e.g., "Backend-2026-Q1").

✅ Restrict Scopes

Only grant permissions that are actually needed. Review and audit key scopes regularly.

❌ Never Expose in Frontend

API keys should never be included in client-side JavaScript. Use JWT tokens for frontend authentication.

❌ Never Commit to Git

Use environment variables or secrets management. Add .env*to .gitignore.

Next Steps

RBAC & Permissions →

Understand roles, permissions, and access control.

Audit Logs →

Track all API activity and security events.