Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt

Use this file to discover all available pages before exploring further.

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:
TypePrefixCreated fromUse case
Tenant keytl_live_ / tl_dev_ConsoleServer-to-server integrations, enterprise workflows
Consumer keytlk_Verify portalPersonal 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:
ScopePermissions
attestations:mintCreate new attestations
attestations:readRead attestation details and proof bundles
attestations:revokeRevoke attestations
issuers:readView issuer information
issuers:writeCreate and manage issuers
users:readView users and roles
users:writeInvite users, manage roles
audit:readQuery 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

  1. Navigate to console.truthlocks.com/api-keys
  2. Click “Create API Key”
  3. Enter a descriptive name (e.g., “Production Backend”)
  4. Select the environment (production or sandbox) and required scopes
  5. 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:
ScopePermissions
consumer:readRead your consumer profile and settings
consumer:writeUpdate your consumer profile and settings
attestations:mintMint new attestations
attestations:readRead your attestations
verify:readVerify attestations

​
Creating a consumer key

1

Open settings

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

Create a key

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

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 TypeLifetimeRefresh
Access Token1 hourVia refresh token
Refresh Token30 daysVia 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.