API Keys

The API Keys app enables your users to generate and manage API keys for programmatic access to your backend services. API keys provide a secure way to authenticate requests, allowing developers to associate API calls with specific users or teams. Hexclave provides prebuilt UI components so users and teams can manage their own keys.

Concepts

The authentication flow

A user or client sends an API request with an API key to your application server. Your server validates the API key with Hexclave, which returns an authenticated User (or Team) object. Your server then processes the request and returns the response.

Two kinds of API keys

Hexclave supports two kinds of API keys:

User API keys - associated with an individual user; calls authenticated with this key act on behalf of that user.
Team API keys - associated with a team; calls authenticated with this key act on behalf of that team. Only users with the $manage_api_keys permission for the team can create or revoke them.

Don’t confuse API Keys with Project Keys. The API Keys app documented here lets your end users issue keys for their accounts and teams. If you want to create or rotate the publishable / secret keys that your Hexclave project uses to call the Hexclave API, that lives in Project Settings → Project Keys instead.

User API keys

User API keys are associated with individual users and allow them to authenticate with your API.

app/components/create-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

app/components/create-api-key.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function CreateApiKey() {
  const user = await hexclaveServerApp.getUser({ or: 'redirect' });

  const apiKey = await user.createApiKey({
    description: "Admin-provisioned API key",
    expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
  });

  return <div>API Key: {apiKey.value}</div>;
}

components/CreateApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + (90 * 24 * 60 * 60 * 1000)), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

views.py

import requests
from django.http import JsonResponse

def create_user_api_key(request):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to create API key: {response.text}")

    return JsonResponse(response.json())

main.py

import requests
import time
from fastapi import Cookie, HTTPException

@app.post("/api/create-user-api-key")
async def create_user_api_key(hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return response.json()

app.py

import requests
import time
from flask import request, jsonify

@app.route('/api/create-user-api-key', methods=['POST'])
def create_user_api_key():
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify(response.json())

Team API keys

Team API keys are associated with teams and can be used to provide access to team resources over your API.

app/components/create-team-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

app/components/create-team-api-key.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const team = await hexclaveServerApp.getTeam(teamId);

  if (!team) {
    return <div>Team not found</div>;
  }

  const teamApiKey = await team.createApiKey({
    description: "Admin-provisioned team API key",
    expiresAt: new Date(Date.now() + (30 * 24 * 60 * 60 * 1000)), // 30 days
  });

  return <div>Team API Key: {teamApiKey.value}</div>;
}

components/CreateTeamApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + (60 * 24 * 60 * 60 * 1000)), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

views.py

import requests
import time
from django.http import JsonResponse

def create_team_api_key(request, team_id):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to create team API key: {response.text}")

    return JsonResponse(response.json())

main.py

import requests
import time
from fastapi import Cookie, HTTPException

@app.post("/api/teams/{team_id}/api-keys")
async def create_team_api_key(team_id: str, hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return response.json()

app.py

import requests
import time
from flask import request, jsonify

@app.route('/api/teams/<team_id>/api-keys', methods=['POST'])
def create_team_api_key(team_id):
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify(response.json())

Enabling the API Keys App

To use API keys in your application, you must enable the API Keys app in your Hexclave dashboard:

Open your Hexclave dashboard
Go to Apps
Find and open API Keys
Click Enable

Dashboard settings

Once enabled, the API Keys app exposes exactly two toggles under API Key Settings:

Setting	Config field	Description
User API Keys	`apiKeys.enabled.user`	Allow users to create API keys for their accounts. Enables the `user-api-keys` backend routes.
Team API Keys	`apiKeys.enabled.team`	Allow users to create API keys for their teams. Enables the `team-api-keys` backend routes.

Both are disabled by default. Changes require clicking Save before they take effect. Toggling User API Keys controls whether the <AccountSettings> component shows its API Keys tab. Toggling Team API Keys controls whether the team settings page shows its API Keys section to users with the $manage_api_keys permission.

Team permission requirement

Creating, listing, and revoking team API keys requires the $manage_api_keys permission on the team. Make sure your team roles grant this permission to the right members (e.g. admins).

Prebuilt UI Components

Hexclave provides prebuilt UI components that let your users manage their own API keys without any additional code.

User API Keys UI

For frameworks that support React components, the <AccountSettings> component includes an API Keys tab where users can:

View all their active API keys
Create new API keys with a description and an expiration date
Revoke existing API keys
See when each key was created and when it expires

The tab is only shown when apiKeys.enabled.user is on for your project.

Next.js
React

app/account/page.tsx

import { AccountSettings } from '@hexclave/next';

export default function MyAccountPage() {
  return <AccountSettings fullPage />;
}

src/account-page.tsx

import { AccountSettings } from '@hexclave/react';

export default function MyAccountPage() {
  return <AccountSettings fullPage />;
}

Team API Keys UI

The team settings page automatically includes an API Keys section when all of the following are true:

The API Keys app is enabled
apiKeys.enabled.team is on for your project
The current user has the $manage_api_keys permission on the team

Users with the right permission can create, list, and revoke team API keys directly from the team settings interface - no extra code required.

The `ApiKey` object

Both user.listApiKeys() and team.listApiKeys() return arrays of ApiKey objects. The same shape comes back from user.createApiKey(...) / team.createApiKey(...), except the value is the full plaintext key only on the first view.

Field	Type	Description
`id`	`string`	Stable identifier for the key
`description`	`string`	Human-readable description set on creation
`createdAt`	`Date`	When the key was created
`expiresAt`	`Date \| undefined`	Optional expiration timestamp
`manuallyRevokedAt`	`Date \| null \| undefined`	Set when the key was explicitly revoked
`value`	`string` (first view) / `{ lastFour: string }`	Full key on first view only, then just the last 4 characters
`type`	`"user" \| "team"`	Which flavor of key this is
`userId` / `teamId`	`string`	The owning user (for `type: "user"`) or team (for `type: "team"`)
`update(options)`	`(options) => Promise<void>`	Update `description`, `expiresAt`, or `revoked`
`revoke()`	`() => Promise<void>`	Convenience for `update({ revoked: true })`
`isValid()`	`() => boolean`	`true` if the key is not expired and not manually revoked
`whyInvalid()`	`() => "manually-revoked" \| "expired" \| null`	Reason the key is invalid, or `null` if it’s still valid

The full plaintext value of an API key is only returned once - at creation time. After that, the SDK only ever exposes value.lastFour. Display, copy, or store the value immediately on creation; it cannot be retrieved later.

`isPublic` keys

When creating a key, pass isPublic: true to exempt it from Hexclave’s secret scanner. The secret scanner automatically revokes API keys it detects in public places (e.g. exposed in a GitHub repo). Use isPublic only for keys that are intentionally exposed to clients (e.g. anonymous-style access tokens).

Working with API Keys

Creating a user API key

app/components/create-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000), // 90 days
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

app/components/create-api-key.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function CreateApiKey() {
  const user = await hexclaveServerApp.getUser({ or: 'redirect' });

  const apiKey = await user.createApiKey({
    description: "Admin-provisioned API key",
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
  });

  return <div>API Key: {apiKey.value}</div>;
}

components/CreateApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function CreateApiKey() {
  const user = useUser({ or: 'redirect' });

  const handleCreateKey = async () => {
    const apiKey = await user.createApiKey({
      description: "My client application",
      expiresAt: new Date(Date.now() + 90 * 24 * 60 * 60 * 1000),
    });

    console.log("API Key created:", apiKey.value);
  };

  return <button onClick={handleCreateKey}>Create API Key</button>;
}

views.py

import requests
import time
from django.http import JsonResponse

def create_user_api_key(request):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to create API key: {response.text}")

    return JsonResponse(response.json())

main.py

import requests
import time
from fastapi import Cookie, HTTPException

@app.post("/api/create-user-api-key")
async def create_user_api_key(hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return response.json()

app.py

import requests
import time
from flask import request, jsonify

@app.route('/api/create-user-api-key', methods=['POST'])
def create_user_api_key():
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Create API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'user_id': 'me',
            'description': 'My client application',
            'expires_at_millis': int((time.time() + 90 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify(response.json())

Creating a team API key

Requires the $manage_api_keys team permission.

app/components/create-team-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

app/components/create-team-api-key.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const team = await hexclaveServerApp.getTeam(teamId);

  if (!team) {
    return <div>Team not found</div>;
  }


  const teamApiKey = await team.createApiKey({
    description: "Admin-provisioned team API key",
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
  });

  return <div>Team API Key: {teamApiKey.value}</div>;
}

components/CreateTeamApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function CreateTeamApiKey({ teamId }: { teamId: string }) {
  const user = useUser({ or: 'redirect' });
  const team = user.useTeam(teamId);

  const handleCreateKey = async () => {
    if (!team) return;

    const teamApiKey = await team.createApiKey({
      description: "Team integration service",
      expiresAt: new Date(Date.now() + 60 * 24 * 60 * 60 * 1000), // 60 days
    });

    console.log("Team API Key created:", teamApiKey.value);
  };

  return <button onClick={handleCreateKey}>Create Team API Key</button>;
}

views.py

import requests
import time
from django.http import JsonResponse

def create_team_api_key(request, team_id):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to create team API key: {response.text}")

    return JsonResponse(response.json())

main.py

import requests
import time
from fastapi import Cookie, HTTPException

@app.post("/api/teams/{team_id}/api-keys")
async def create_team_api_key(team_id: str, hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return response.json()

app.py

import requests
import time
from flask import request, jsonify

@app.route('/api/teams/<team_id>/api-keys', methods=['POST'])
def create_team_api_key(team_id):
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Create team API key via client API
    response = requests.post(
        'https://api.hexclave.com/api/v1/team-api-keys',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'team_id': team_id,
            'description': 'Team integration service',
            'expires_at_millis': int((time.time() + 60 * 24 * 60 * 60) * 1000),
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify(response.json())

Listing API keys

app/components/api-keys-list.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function ApiKeysList() {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  return (
    <div>
      <h2>Your API Keys</h2>
      {apiKeys.map(key => (
        <div key={key.id}>
          <p>{key.description}</p>
          <p>Last 4 digits: {key.value.lastFour}</p>
          <p>Created: {key.createdAt.toLocaleDateString()}</p>
        </div>
      ))}
    </div>
  );
}

app/components/api-keys-list.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function ApiKeysList() {
  const user = await hexclaveServerApp.getUser({ or: 'redirect' });
  const apiKeys = await user.listApiKeys();

  return (
    <div>
      <h2>Your API Keys</h2>
      {apiKeys.map(key => (
        <div key={key.id}>
          <p>{key.description}</p>
          <p>Last 4 digits: {key.value.lastFour}</p>
          <p>Created: {key.createdAt.toLocaleDateString()}</p>
        </div>
      ))}
    </div>
  );
}

components/ApiKeysList.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function ApiKeysList() {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  return (
    <div>
      <h2>Your API Keys</h2>
      {apiKeys.map(key => (
        <div key={key.id}>
          <p>{key.description}</p>
          <p>Last 4 digits: {key.value.lastFour}</p>
          <p>Created: {key.createdAt.toLocaleDateString()}</p>
        </div>
      ))}
    </div>
  );
}

views.py

import requests
from django.http import JsonResponse

def list_user_api_keys(request):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # List user's API keys via client API
    response = requests.get(
        'https://api.hexclave.com/api/v1/user-api-keys?user_id=me',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to list API keys: {response.text}")

    return JsonResponse(response.json(), safe=False)

main.py

import requests
from fastapi import Cookie, HTTPException

@app.get("/api/user-api-keys")
async def list_user_api_keys(hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # List user's API keys via client API
    response = requests.get(
        'https://api.hexclave.com/api/v1/user-api-keys?user_id=me',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return response.json()

app.py

import requests
from flask import request, jsonify

@app.route('/api/user-api-keys', methods=['GET'])
def list_user_api_keys():
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # List user's API keys via client API
    response = requests.get(
        'https://api.hexclave.com/api/v1/user-api-keys?user_id=me',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify(response.json())

The same pattern works for team API keys via team.useApiKeys() (client) or team.listApiKeys() (server), and the /api/v1/team-api-keys REST endpoint.

Validating an incoming API key on your server

This is the core authentication flow: an incoming request includes an API key, and your server needs to know which user or team it represents. Pass the plaintext key directly to hexclaveServerApp.getUser({ apiKey }) or hexclaveServerApp.getTeam({ apiKey }) - Hexclave validates it and returns the corresponding object, or null if the key is invalid, expired, or revoked.

Next.js Server
Team key (Next.js Server)
Django
FastAPI
Flask

app/api/protected/route.ts

import { hexclaveServerApp } from "@/hexclave/server";

export async function GET(request: Request) {
  const auth = request.headers.get("authorization");
  const apiKey = auth?.replace(/^Bearer\s+/i, "");
  if (!apiKey) {
    return new Response("Missing API key", { status: 401 });
  }

  const user = await hexclaveServerApp.getUser({ apiKey });
  if (!user) {
    return new Response("Invalid API key", { status: 401 });
  }

  return Response.json({ userId: user.id, displayName: user.displayName });
}

app/api/team-protected/route.ts

import { hexclaveServerApp } from "@/hexclave/server";

export async function GET(request: Request) {
  const apiKey = request.headers.get("authorization")?.replace(/^Bearer\s+/i, "");
  if (!apiKey) return new Response("Missing API key", { status: 401 });

  const team = await hexclaveServerApp.getTeam({ apiKey });
  if (!team) return new Response("Invalid team API key", { status: 401 });

  return Response.json({ teamId: team.id, displayName: team.displayName });
}

views.py

import requests
from django.http import JsonResponse

def protected_view(request):
    auth_header = request.headers.get('Authorization', '')
    if not auth_header.startswith('Bearer '):
        return JsonResponse({'error': 'Missing API key'}, status=401)
    api_key = auth_header[len('Bearer '):]

    # Check the API key via server API
    check = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys/check',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
        json={'api_key': api_key},
    )

    if check.status_code != 200:
        return JsonResponse({'error': 'Invalid API key'}, status=401)

    api_key_obj = check.json()
    # Fetch the owning user
    user_resp = requests.get(
        f'https://api.hexclave.com/api/v1/users/{api_key_obj["user_id"]}',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
    )
    user = user_resp.json()
    return JsonResponse({'userId': user['id'], 'displayName': user.get('display_name')})

main.py

import requests
from fastapi import Header, HTTPException

@app.get("/api/protected")
async def protected_view(authorization: str = Header(None)):
    if not authorization or not authorization.startswith('Bearer '):
        raise HTTPException(status_code=401, detail="Missing API key")
    api_key = authorization[len('Bearer '):]

    # Check the API key via server API
    check = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys/check',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
        json={'api_key': api_key},
    )

    if check.status_code != 200:
        raise HTTPException(status_code=401, detail="Invalid API key")

    api_key_obj = check.json()
    user_resp = requests.get(
        f'https://api.hexclave.com/api/v1/users/{api_key_obj["user_id"]}',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
    )
    user = user_resp.json()
    return {'userId': user['id'], 'displayName': user.get('display_name')}

app.py

import requests
from flask import request, jsonify

@app.route('/api/protected', methods=['GET'])
def protected_view():
    auth_header = request.headers.get('Authorization', '')
    if not auth_header.startswith('Bearer '):
        return jsonify({'error': 'Missing API key'}), 401
    api_key = auth_header[len('Bearer '):]

    # Check the API key via server API
    check = requests.post(
        'https://api.hexclave.com/api/v1/user-api-keys/check',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
        json={'api_key': api_key},
    )

    if check.status_code != 200:
        return jsonify({'error': 'Invalid API key'}), 401

    api_key_obj = check.json()
    user_resp = requests.get(
        f'https://api.hexclave.com/api/v1/users/{api_key_obj["user_id"]}',
        headers={
            'x-hexclave-access-type': 'server',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-secret-server-key': hexclave_secret_server_key,
        },
    )
    user = user_resp.json()
    return jsonify({'userId': user['id'], 'displayName': user.get('display_name')})

Checking an existing key’s validity

When you already hold an ApiKey object (e.g. from useApiKeys()), use its synchronous helpers isValid() and whyInvalid(). The latter returns "manually-revoked", "expired", or null.

app/components/check-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function CheckApiKeyValidity({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const apiKey = apiKeys.find(key => key.id === apiKeyId);

  if (!apiKey) {
    return <div>API key not found</div>;
  }

  if (apiKey.isValid()) {
    return <div>API key is valid</div>;
  }

  const reason = apiKey.whyInvalid();
  return <div>API key is invalid: {reason}</div>;
}

app/components/check-api-key.tsx

import { hexclaveServerApp } from "@/hexclave/server";

export default async function CheckApiKeyValidity({
  userId,
  apiKeyId
}: {
  userId: string,
  apiKeyId: string
}) {
  const user = await hexclaveServerApp.getUser(userId);
  if (!user) return <div>User not found</div>;

  const apiKeys = await user.listApiKeys();
  const apiKey = apiKeys.find(key => key.id === apiKeyId);

  if (!apiKey) {
    return <div>API key not found</div>;
  }

  if (apiKey.isValid()) {
    return <div>API key is valid</div>;
  }

  const reason = apiKey.whyInvalid();
  return <div>API key is invalid: {reason}</div>;
}

components/CheckApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function CheckApiKeyValidity({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const apiKey = apiKeys.find(key => key.id === apiKeyId);

  if (!apiKey) {
    return <div>API key not found</div>;
  }

  if (apiKey.isValid()) {
    return <div>API key is valid</div>;
  }

  const reason = apiKey.whyInvalid();
  return <div>API key is invalid: {reason}</div>;
}

views.py

import requests
import time
from django.http import JsonResponse

def check_api_key_validity(request, api_key_id):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Get API key details via client API
    response = requests.get(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        }
    )

    if response.status_code != 200:
        return JsonResponse({'error': 'API key not found'}, status=404)

    api_key = response.json()

    # Check if manually revoked
    if api_key.get('manually_revoked_at_millis'):
        return JsonResponse({
            'valid': False,
            'reason': 'manually-revoked'
        })

    # Check if expired
    if api_key.get('expires_at_millis'):
        if api_key['expires_at_millis'] < time.time() * 1000:
            return JsonResponse({
                'valid': False,
                'reason': 'expired'
            })

    return JsonResponse({'valid': True})

main.py

import requests
import time
from fastapi import Cookie, HTTPException

@app.get("/api/check-api-key/{api_key_id}")
async def check_api_key_validity(api_key_id: str, hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Get API key details via client API
    response = requests.get(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=404, detail="API key not found")

    api_key = response.json()

    # Check if manually revoked
    if api_key.get('manually_revoked_at_millis'):
        return {
            'valid': False,
            'reason': 'manually-revoked'
        }

    # Check if expired
    if api_key.get('expires_at_millis'):
        if api_key['expires_at_millis'] < time.time() * 1000:
            return {
                'valid': False,
                'reason': 'expired'
            }

    return {'valid': True}

app.py

import requests
import time
from flask import request, jsonify

@app.route('/api/check-api-key/<api_key_id>', methods=['GET'])
def check_api_key_validity(api_key_id):
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Get API key details via client API
    response = requests.get(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        }
    )

    if response.status_code != 200:
        return jsonify({'error': 'API key not found'}), 404

    api_key = response.json()

    # Check if manually revoked
    if api_key.get('manually_revoked_at_millis'):
        return jsonify({
            'valid': False,
            'reason': 'manually-revoked'
        })

    # Check if expired
    if api_key.get('expires_at_millis'):
        if api_key['expires_at_millis'] < time.time() * 1000:
            return jsonify({
                'valid': False,
                'reason': 'expired'
            })

    return jsonify({'valid': True})

Revoking an API key

API keys can be revoked when they are no longer needed or if they have been compromised. Revoking is irreversible: a revoked key’s manuallyRevokedAt becomes set and isValid() returns false (whyInvalid() returns "manually-revoked").

app/components/revoke-api-key.tsx

"use client";
import { useUser } from "@hexclave/next";

export default function RevokeApiKey({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const handleRevoke = async () => {
    const apiKeyToRevoke = apiKeys.find(key => key.id === apiKeyId);

    if (apiKeyToRevoke) {
      await apiKeyToRevoke.revoke();
      console.log("API Key revoked");
    }
  };

  return <button onClick={handleRevoke}>Revoke API Key</button>;
}

lib/api-keys.ts

import { hexclaveServerApp } from "@/hexclave/server";

export async function revokeApiKey(userId: string, apiKeyId: string) {
  const user = await hexclaveServerApp.getUser(userId);
  if (!user) return;

  const apiKeys = await user.listApiKeys();
  const apiKeyToRevoke = apiKeys.find(key => key.id === apiKeyId);

  if (apiKeyToRevoke) {
    await apiKeyToRevoke.revoke();
  }
}

components/RevokeApiKey.tsx

"use client";
import { useUser } from "@hexclave/react";

export default function RevokeApiKey({ apiKeyId }: { apiKeyId: string }) {
  const user = useUser({ or: 'redirect' });
  const apiKeys = user.useApiKeys();

  const handleRevoke = async () => {
    const apiKeyToRevoke = apiKeys.find(key => key.id === apiKeyId);

    if (apiKeyToRevoke) {
      await apiKeyToRevoke.revoke();
      console.log("API Key revoked");
    }
  };

  return <button onClick={handleRevoke}>Revoke API Key</button>;
}

views.py

import requests
from django.http import JsonResponse

def revoke_api_key(request, api_key_id):
    # Get the current user's access token from session/cookie
    access_token = request.COOKIES.get('hexclave-access-token')

    # Revoke API key via client API (update with revoked: true)
    response = requests.patch(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'revoked': True,
        }
    )

    if response.status_code != 200:
        raise Exception(f"Failed to revoke API key: {response.text}")

    return JsonResponse({'message': 'API key revoked successfully'})

main.py

import requests
from fastapi import Cookie, HTTPException

@app.delete("/api/user-api-keys/{api_key_id}")
async def revoke_api_key(api_key_id: str, hexclave_access_token: str = Cookie(None, alias="hexclave-access-token")):
    if not hexclave_access_token:
        raise HTTPException(status_code=401, detail="Not authenticated")

    # Revoke API key via client API (update with revoked: true)
    response = requests.patch(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': hexclave_access_token,
        },
        json={
            'revoked': True,
        }
    )

    if response.status_code != 200:
        raise HTTPException(status_code=response.status_code, detail=response.text)

    return {"message": "API key revoked successfully"}

app.py

import requests
from flask import request, jsonify

@app.route('/api/user-api-keys/<api_key_id>', methods=['DELETE'])
def revoke_api_key(api_key_id):
    access_token = request.cookies.get('hexclave-access-token')
    if not access_token:
        return jsonify({'error': 'Not authenticated'}), 401

    # Revoke API key via client API (update with revoked: true)
    response = requests.patch(
        f'https://api.hexclave.com/api/v1/user-api-keys/{api_key_id}',
        headers={
            'x-hexclave-access-type': 'client',
            'x-hexclave-project-id': hexclave_project_id,
            'x-hexclave-publishable-client-key': hexclave_publishable_client_key,
            'x-hexclave-access-token': access_token,
        },
        json={
            'revoked': True,
        }
    )

    if response.status_code != 200:
        return jsonify({'error': response.text}), response.status_code

    return jsonify({'message': 'API key revoked successfully'})

Best Practices

Show the value once. API key values are returned in plaintext only at creation. Always display, copy, or send them immediately - don’t expect to fetch them again later.
Set sensible expirations. Long-lived keys are convenient but risky. Default to short expirations (30–90 days) and let users rotate.
Don’t share user keys across users. A user API key acts as that exact user. If a service needs to act independently, prefer a team API key with a service-style role.
Use $manage_api_keys deliberately. Only grant this team permission to roles you’d trust to lock or unlock the entire team’s programmatic access.
Mark public keys with isPublic: true. This opts them out of the secret scanner so your legitimately-public keys don’t get auto-revoked.
Use getUser({ apiKey }) / getTeam({ apiKey }) for validation. Never try to parse or compare the plaintext value yourself - Hexclave handles hashing, expiration, and revocation.

Getting Started

Going Further

Apps

Integrations

Other

Concepts

The authentication flow

Two kinds of API keys

User API keys

Team API keys

Enabling the API Keys App

Dashboard settings

Team permission requirement

Prebuilt UI Components

User API Keys UI

Team API Keys UI

The `ApiKey` object

`isPublic` keys

Working with API Keys

Creating a user API key

Creating a team API key

Listing API keys

Validating an incoming API key on your server

Checking an existing key’s validity

Revoking an API key

Best Practices

​Concepts

​The authentication flow

​Two kinds of API keys

​User API keys

​Team API keys

​Enabling the API Keys App

​Dashboard settings

​Team permission requirement

​Prebuilt UI Components

​User API Keys UI

​Team API Keys UI

​The ApiKey object

​isPublic keys

​Working with API Keys

​Creating a user API key

​Creating a team API key

​Listing API keys

​Validating an incoming API key on your server

​Checking an existing key’s validity

​Revoking an API key

​Best Practices

Concepts

The authentication flow

Two kinds of API keys

User API keys

Team API keys

Enabling the API Keys App

Dashboard settings

Team permission requirement

Prebuilt UI Components

User API Keys UI

Team API Keys UI

The `ApiKey` object

`isPublic` keys

Working with API Keys

Creating a user API key

Creating a team API key

Listing API keys

Validating an incoming API key on your server

Checking an existing key’s validity

Revoking an API key

Best Practices