API Keys

API keys are authentication tokens that allow access to Almirant from external tools, scripts, or programmatic integrations. They are the primary mechanism for connecting MCP clients like Claude Code, CI/CD automations, or any service that needs to interact with the Almirant API.

What they are used for

API keys are mainly used for:

• Connecting Claude Code -- Authenticating the Almirant MCP server so that Claude Code can manage projects, boards, and work items. See the MCP Authentication guide for more details.
• Automations -- Scripts or CI/CD pipelines that create work items, update statuses, or record AI sessions.
• Custom integrations -- Your own applications that interact with the Almirant API.

Generating an API key

1. Go to Settings > API Keys.
2. Click Generate new API Key.
3. Enter a descriptive name to identify the key's purpose (for example: "Claude Code - Work laptop", "CI/CD Pipeline", "Internal bot").
4. Select the permissions the key will have.
5. Click Create.
6. Copy the API key immediately.

Copy the key now

The complete API key is only shown once at the time of creation. If you close the dialog without copying it, you will not be able to recover it and will need to generate a new one.

Using the API key

API keys are sent in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer your-api-key-here" \
  https://api.almirant.ai/api/projects

Configuration for MCP (Claude Code)

To use the API key with the Almirant MCP server in Claude Code, add the following configuration to your project's .mcp.json file:

{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp?projectId=project-uuid",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

For local development, replace the URL with http://localhost:3001/mcp?projectId=project-uuid.

See the complete MCP Authentication and Project Scoping reference for more configuration options.

Managing API keys

Viewing existing keys

From Settings > API Keys you can see the list of all generated keys with:

Field	Description
Name	Descriptive name assigned when creating the key
Prefix	First characters of the key for identification (the rest is hidden)
Creation date	When the key was generated
Last used	Date of the last authenticated request with this key

Revoking an API key

If an API key is compromised or no longer needed:

1. Go to Settings > API Keys.
2. Find the key in the list.
3. Click Revoke.
4. Confirm the revocation.

danger

Revoking an API key is immediate and irreversible. Any service or tool using that key will stop working instantly. Make sure to update the configurations of affected services before revoking.

Security best practices

API key security

API keys provide access to your organization's data. Treat them with the same level of security as a password.

• One key per service -- Generate a different API key for each tool or service. If one is compromised, you can revoke it without affecting the rest.
• Descriptive names -- Use names that clearly identify where the key is used: "Claude Code - Office PC", "GitHub Actions - Deploy", "Slack Bot - Notifications".
• Do not share keys -- Each team member who needs MCP access should generate their own API key.
• Do not include keys in code -- Never commit API keys to code repositories. Use environment variables or secret managers.
• Review periodically -- Revoke keys that are no longer in use or whose purpose you do not recognize.
• Rotate compromised keys -- If you suspect a key has been leaked, revoke it immediately and generate a new one.

Example of secure usage with environment variables

Instead of writing the key directly in configuration files:

# .env (excluded from git via .gitignore)
ALMIRANT_API_KEY=your-api-key-here

// .mcp.json (use environment variable reference if your tool supports it)
{
  "mcpServers": {
    "almirant": {
      "type": "http",
      "url": "https://api.almirant.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${ALMIRANT_API_KEY}"
      }
    }
  }
}

For Developers

Authentication architecture

API keys are stored in hashed form in the apiKeys database schema table. The authentication flow is:

1. The client sends the API key in the Authorization: Bearer <key> header.
2. The backend looks up the hashed key in the apiKeys table.
3. If the key is valid, the associated user and organization are retrieved.
4. The authentication context ({ user, organizationId }) is injected into the request.
5. Protected routes use this context to filter data by organization.

Relevant endpoints

Method	Route	Description
GET	/api/api-keys	Lists the organization's API keys
POST	/api/api-keys	Generates a new API key
DELETE	/api/api-keys/:id	Revokes an API key

Permissions and scopes

API keys inherit the permissions of the user who created them. The key's scope is limited to the user's organization.