Skip to main content

Generating API keys

API keys let you access Docana programmatically and integrate it into your applications. Here's how to create one.

Prerequisites

You need to have a Docana account with appropriate permissions to generate API keys. Contact your organization administrator if you don't have access to the Developer section.

Step 1: Open API keys​

Sign in to the platform and open API Keys. The list shows each key’s name, scope, status, last use, and expiration. Select + Create API Key.

The API keys list shows each key’s scope, status, last use, and expiration.
The API keys list shows each key’s scope, status, last use, and expiration.

Step 2: Choose access and expiration​

Give the key a name that identifies the system using it, then choose a scope:

ScopeUse it for
Full accessBackend integrations that need the general API surface. Access remains limited by the owner’s permissions.
Widget onlyWidget chat, history, and archive endpoints. See Web Widget.
Routine onlyTriggering routines from another system.

Choose an expiration: 1 hour, 1 day, 1 week, 1 month, 1 year, or Never. Expired and revoked keys can no longer authenticate requests.

Choose the scope and expiration before creating the key.
Choose the scope and expiration before creating the key.

Step 3: Create and save the key​

Select Create, then Copy. Save the value in your environment variables or secrets manager before closing the dialog. The full key is only shown once.

Copy the new key before closing the dialog. The secret is hidden in this screenshot.
Copy the new key before closing the dialog. The secret is hidden in this screenshot.

Keep full-access keys in server-side code. For a widget or routine integration, choose the scope intended for that endpoint. Never commit a real key to version control.

Using your API key​

Check a Full access key by requesting the current user. This reads your account information and confirms authentication. Widget-only and routine-only keys must be used with their respective endpoints.

Send API keys in the Authorization header using the ApiKey scheme, not as a Bearer token:

Authorization: ApiKey your_api_key_here

cURL example​

export DOCANA_API_KEY="your_api_key_here"

curl "https://platform.docana.com/api/v1/users/me/" \
  -H "Authorization: ApiKey ${DOCANA_API_KEY}"

TypeScript/JavaScript example​

Run this in a server-side environment with DOCANA_API_KEY set:

const response = await fetch('https://platform.docana.com/api/v1/users/me/', {
  headers: {
    Authorization: `ApiKey ${process.env.DOCANA_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error(`Authentication check failed: HTTP ${response.status}`);
}

const currentUser = await response.json();
console.log(currentUser);

If the request returns 401 or 403, check the key’s expiration, scope, and owner permissions. See API errors for the status codes and troubleshooting steps.

Managing API keys​

Viewing key details​

From the API Keys list, you can see:

  • ID: Unique identifier for the key
  • Name: The descriptive name you provided
  • Status: Whether the key is active or revoked
  • Created At: When the key was created
  • Last Used: The last time the key was used (useful for identifying unused keys)
  • Expires At: When the key will expire

Revoking a key​

If a key is compromised or you don't need it anymore:

  1. Go to the API Keys page
  2. Find the key you want to revoke
  3. Click the delete icon
  4. Confirm the action
danger

This happens immediately and you can't undo it. Any applications using that key will stop working right away.

Best practices​

  1. Use clear names: Name keys based on what they're for (e.g., "Production App", "Staging Environment", "CI/CD").

  2. Set expiration: Balance security with how you work. Shorter expiration times are more secure.

  3. Rotate keys regularly: Even if keys haven't expired, rotate them periodically for security.

  4. Use environment variables: Never put API keys in your code. Use environment variables or a secrets manager.

  5. Use the narrowest scope: pick Widget only for website widgets and Routine only for scheduled triggers. A leaked narrow key is a much smaller problem than a leaked full-access key.

  6. Check usage: Look at the "Last Used" column regularly to find keys you don't need anymore.

Next steps​

  • API Overview: Authentication and the main endpoints
  • CLI: Use your key from the terminal
  • MCP Servers: Set up Model Context Protocol integrations
  • Integrations: Set up external service integrations