Identity & Recipients

Locktera enforces access control using recipient identities defined in container access policies.

Recipients identify who is allowed to decode and access a container.

Most applications already maintain their own user system. Locktera is designed to integrate with your existing identity model rather than replace it.

How Recipients Work

Recipients are defined in the container manifest when encoding a container.

Example manifest:

{
  "container": {
    "recipients": [
      "authorized.user@company.com"
    ]
  }
}

Only listed recipients are allowed to decode the container.

All decode requests are validated against the container’s current recipient list. Recipient validation occurs before any container decryption is permitted.

Recipient Identity Format

Recipients are identified using email addresses.

Example:

{
  "container": {
    "recipients": [
      "user1@company.com",
      "user2@company.com"
    ]
  }
}

The email address must match the identity associated with the requesting API key or authenticated user. Recipient identity is cryptographically bound to container access policies.

How This Integrates with Your User System

Most applications maintain their own users. Locktera does not require you to migrate or replace your identity system.

Typical integration pattern:

Your internal user → email address → Locktera recipient

Example:

Internal User ID: 847392
Email: user@company.com

Manifest recipients:
"user@company.com"

When that user attempts to decode the container, Locktera verifies that their identity matches an authorized recipient.

Authentication and Identity Verification

When a decode request is made, Locktera evaluates:

• The identity associated with the API key
• The container recipient list
• Any additional DRM restrictions

If the identity is authorized, decode is allowed.

If not, the request is denied.

HTTP 403 Forbidden

{
  "error": "access_denied",
  "message": "Access is not permitted for this container"
}

Updating Recipients

If the container was created with dynamic DRM enabled, recipients can be updated.

Endpoint:

PATCH /users/{user_id}/containers/{container_id}/drm

Example request:

curl -X PATCH $BASE_URL/users/YOUR_USER_ID/containers/CONTAINER_ID/drm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "recipients": ["new.user@company.com"]
      }'

Changes take effect immediately.

Optional: Provisioning Locktera Users

Locktera also provides optional APIs to create and manage users directly.

This can be useful for:

• Automated provisioning
• Enterprise identity synchronization
• Administrative workflows

However, this is not required for most integrations.

See the Users API section for details.

Best Practices

• Use email addresses that match your application’s user identities
• Store container IDs and recipient lists in your application database
• Update recipients when access needs change
• Use dynamic DRM for flexible access control

Summary

Recipients define who can access a container.

Recipients:

• Are identified by email address
• Are defined in the container manifest
• Are enforced cryptographically
• Can be updated if dynamic DRM is enabled

Locktera integrates with your existing identity system using recipient email addresses.