Skip to main content
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:

Passing your key

Include your API key using either of these headers:
You can also use the Authorization header with the ApiKey scheme:
These formats authenticate API-key-enabled endpoints. Some operations require a user bearer token and role checks; public health endpoints need neither. 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

Scopes

Tenant API keys can be restricted to specific permissions:
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
Response
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:

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:
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

Token Structure

Token Lifetime

Authenticator MFA for Console accounts

In Console, open Settings → Security → Authenticator MFA to connect Google Authenticator or another time-based authenticator app.
  1. Confirm your current local Truthlocks password.
  2. Scan the private QR code, or enter the setup key in your authenticator as a time-based account.
  3. Enter the six-digit code from the app to enable MFA.
  4. Save the ten recovery codes shown after confirmation. They are displayed once, and each code works once.
New sign-ins require the second factor after either your password or your business identity provider. The verification step expires after five minutes. Repeated incorrect codes temporarily lock verification for the account. A code that has already been accepted cannot be reused. To replace recovery codes or disable MFA, confirm your password and a fresh authenticator code or unused recovery code. Replacing recovery codes invalidates the previous set. SSO users who have never set a local Truthlocks password can use the password-reset flow for their registered email before enrollment. MFA enrollment applies to your own account. It does not enroll other members or impose a workspace-wide MFA requirement. Enabling MFA does not automatically revoke existing sessions. API keys remain separate system credentials.

Security Best Practices

✅ Use Secrets Management

Store API keys in Google Secret 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.