> ## 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.

# Authentication

> API authentication methods, key management, and security best practices.

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

## Authentication Methods

<CardGroup cols={2}>
  <Card title="API Keys" icon="key">
    Long-lived credentials for server-to-server communication. Recommended for
    backend services.
  </Card>

  <Card title="Bearer Tokens (JWT)" icon="passport">
    Short-lived tokens for authenticated users. Ideal for frontend applications
    and user context.
  </Card>
</CardGroup>

## 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](https://console.truthlocks.com)      | Server-to-server integrations, enterprise workflows         |
| **Consumer key** | `tlk_`                 | [Verify portal](https://verify.truthlocks.com) | Personal API access for content protection and verification |

### Passing your key

Include your API key using either of these headers:

```bash theme={null}
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:

```bash theme={null}
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

```text theme={null}
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                           |

<Info>
  **Principle of least privilege:** Only grant the scopes your application
  actually needs. A key with `attestations:mint` only should not also have
  `users:write`.
</Info>

### Creating a tenant key

#### Via console

1. Navigate to [console.truthlocks.com/api-keys](https://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

```bash Request theme={null}
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"]
  }'
```

```json Response theme={null}
{
  "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"
}
```

<Warning>
  **Critical:** The `secret` field is only returned once at creation time. Store
  it immediately in a secrets manager.
</Warning>

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

<Steps>
  <Step title="Open settings">
    In the verify portal sidebar, go to **Settings > API Keys**.
  </Step>

  <Step title="Create a key">
    Click **Create API Key**, enter a descriptive name, and confirm. The full
    secret is displayed once — copy and store it securely.
  </Step>

  <Step title="Use the key">
    Pass the key in the `X-API-Key` header with every request:

    ```bash theme={null}
    curl -X GET https://api.truthlocks.com/v1/consumer/protections \
      -H "X-API-Key: tlk_your_key_here"
    ```
  </Step>
</Steps>

For full details on managing consumer keys, see the [consumer portal guide](/guides/consumer-portal#api-keys).

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

```bash theme={null}
curl -X GET https://api.truthlocks.com/v1/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
```

### Token Structure

```json theme={null}
{
  "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

<CardGroup cols={1}>
  <Card title="✅ Use Secrets Management" icon="vault">
    Store API keys in AWS Secrets Manager, HashiCorp Vault, or similar. Never
    hardcode keys in application code.
  </Card>

  <Card title="✅ Rotate Keys Regularly" icon="rotate">
    Create new keys and revoke old ones periodically. Use descriptive names with
    dates (e.g., "Backend-2026-Q1").
  </Card>

  <Card title="✅ Restrict Scopes" icon="shield-check">
    Only grant permissions that are actually needed. Review and audit key scopes
    regularly.
  </Card>

  <Card title="❌ Never Expose in Frontend" icon="triangle-exclamation">
    API keys should never be included in client-side JavaScript. Use JWT tokens
    for frontend authentication.
  </Card>

  <Card title="❌ Never Commit to Git" icon="github">
    Use environment variables or secrets management. Add `.env*` to
    `.gitignore`.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Consumer portal" icon="user" href="/guides/consumer-portal">
    Manage consumer API keys, protections, and settings.
  </Card>

  <Card title="Environments" icon="server" href="/environments">
    Sandbox vs. production configuration and base URLs.
  </Card>

  <Card title="RBAC & permissions" icon="users-gear" href="/security/rbac">
    Understand roles, permissions, and access control.
  </Card>

  <Card title="Audit logs" icon="list-check" href="/security/audit">
    Track all API activity and security events.
  </Card>
</CardGroup>