Authentication - Truthlocks Documentation

Truthlocks 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

Truthlocks has two types of API keys depending on how you use the platform:

Type	Prefix	Created from	Use case
Tenant key	`tl_live_` / `tl_dev_`	Console	Server-to-server integrations, enterprise workflows
Consumer key	`tlk_`	Verify portal	Personal API access for content protection and verification

Passing your key

Include your API key using either of these headers:

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

You can also use the Authorization header with the ApiKey scheme:

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

Both formats are accepted on all endpoints. X-API-Key is more common in examples throughout this documentation.

Tenant API keys

Tenant keys are the primary authentication method for organizations using Truthlocks. They are scoped to a tenant and support fine-grained permissions.

Key structure

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

Scopes

Tenant 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:mint only should not also have users:write.

Creating a tenant key

Via console

Navigate to console.truthlocks.com/api-keys
Click “Create API Key”
Enter a descriptive name (e.g., “Production Backend”)
Select the environment (production or sandbox) and required scopes
Copy the key immediately — it won’t be shown again

Via API

Request

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.

Consumer API keys

Consumer keys let individual users access the protect and verify APIs programmatically — for example, to mint attestations from a CI pipeline or integrate content protection into your own tools.

Key details

Each account supports up to 5 active keys.
Keys expire automatically after 90 days.
Revoked or expired keys cannot be reactivated — create a new one instead.

Fixed scopes

Consumer keys are issued with a fixed set of scopes that cannot be customized:

Scope	Permissions
`consumer:read`	Read your consumer profile and settings
`consumer:write`	Update your consumer profile and settings
`attestations:mint`	Mint new attestations
`attestations:read`	Read your attestations
`verify:read`	Verify attestations

Creating a consumer key

Open settings

In the verify portal sidebar, go to Settings > API Keys.

Create a key

Click Create API Key, enter a descriptive name, and confirm. The full secret is displayed once — copy and store it securely.

Use the key

Pass the key in the X-API-Key header with every request:

curl -X GET https://api.truthlocks.com/v1/consumer/protections \
  -H "X-API-Key: tlk_your_key_here"

For full details on managing consumer keys, see the consumer portal guide.

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

Consumer portal

Manage consumer API keys, protections, and settings.

Environments

Sandbox vs. production configuration and base URLs.

RBAC & permissions

Understand roles, permissions, and access control.

Audit logs

Track all API activity and security events.

​Authentication Methods

API Keys

Bearer Tokens (JWT)

​API keys

​Passing your key

​Tenant API keys

​Key structure

​Scopes

​Creating a tenant key

​Via console

​Via API

​Consumer API keys

​Key details

​Fixed scopes

​Creating a consumer key

​Bearer Tokens (JWT)

​Using Bearer Tokens

​Token Structure

​Token Lifetime

​Security Best Practices

✅ Use Secrets Management

✅ Rotate Keys Regularly

✅ Restrict Scopes

❌ Never Expose in Frontend

❌ Never Commit to Git

​Next steps

Consumer portal

Environments

RBAC & permissions

Audit logs

Authentication Methods

API keys

Passing your key

Tenant API keys

Key structure

Scopes

Creating a tenant key

Via console

Via API

Consumer API keys

Key details

Fixed scopes

Creating a consumer key

Bearer Tokens (JWT)

Using Bearer Tokens

Token Structure

Token Lifetime

Security Best Practices

Next steps