Skip to content

Authentication

Deeplake uses API tokens for authentication. All SDK and REST operations require a valid token.

Get your API token

  1. Sign in at deeplake.ai
  2. Go to Settings → API Tokens
  3. Click Create API Token
  4. Copy the token

Setup

Store credentials in environment variables:

export DEEPLAKE_API_KEY="your-token-here"
export DEEPLAKE_WORKSPACE="your-workspace"

The Python SDK reads DEEPLAKE_API_KEY and DEEPLAKE_WORKSPACE from the environment automatically. Once exported, you can create a client with no arguments:

from deeplake import Client

client = Client()

You can also pass them explicitly. Useful when managing multiple tokens or workspaces:

import os
from deeplake import Client

client = Client(
    token=os.environ["DEEPLAKE_API_KEY"],
    workspace_id=os.environ["DEEPLAKE_WORKSPACE"],
)

export DEEPLAKE_ORG_ID="your-org-id"
API_URL="https://api.deeplake.ai"

# All requests need these headers
curl -s "$API_URL/workspaces/$DEEPLAKE_WORKSPACE/tables" \
  -H "Authorization: Bearer $DEEPLAKE_API_KEY" \
  -H "X-Activeloop-Org-Id: $DEEPLAKE_ORG_ID"

How the token works

The API token is a JWT. The SDK automatically extracts org_id from the token claims - you don't need to pass it explicitly.

client = Client()
print(client.org_id)  # automatically extracted from the token

Error handling

from deeplake import Client
from deeplake.managed import AuthError, TokenError

try:
    client = Client()
except TokenError as e:
    print(f"Token error: {e}")
except AuthError as e:
    print(f"Auth error: {e}")
Error Cause Fix
Token required No token or DEEPLAKE_API_KEY env var set Export DEEPLAKE_API_KEY or pass token=
Token does not contain org_id Missing claim Ensure token is an API token from deeplake.ai
Unauthorized: invalid or expired Token expired Generate a new token

Next steps

  • Tables: create and query tables
  • Search: vector, BM25, and hybrid search