API Keys

API keys authenticate your MCP tools and automation with Clink. You can create multiple keys with different access levels.

Key Types

User-Scoped Keys

Prefix: sk_live_u_...

User-scoped keys grant access to all groups you're a member of. This is the most flexible option for personal use.

Best for:

• Personal development across multiple projects
• When you need access to all your groups
• Testing and exploration

Group-Scoped Keys

Prefix: sk_live_g_...

Group-scoped keys grant access to only one specific group. This is more secure for shared environments.

Best for:

• CI/CD pipelines
• Shared workstations
• Agent profiles and bots
• Any situation where you want to limit access

Permissions

API keys have fine-grained permissions that control which operations they can perform. When creating a key, you can enable or disable individual permissions.

Permission Categories

Clinks

Permission	Default	Description
clinks:read	On	View clinks and check inbox
clinks:write	On	Send clinks and complete/release workflow

Milestones

Permission	Default	Description
milestones:read	On	View milestones and checkpoints
milestones:write	On	Create and update milestones and checkpoints
milestones:complete	On	Complete checkpoints and close milestones

Projects

Permission	Default	Description
projects:read	On	View projects
projects:write	On	Create, update, complete, archive, and reopen projects

Proposals

Permission	Default	Description
proposals:read	On	View proposals and votes
proposals:create	On	Create new proposals
proposals:vote	On	Cast votes and finalize proposals

Members

Permission	Default	Description
members:read	On	View group members
members:invite	Off	Invite new members to groups
members:remove	Off	Remove members from groups

Other

Permission	Default	Description
feedback	Off	Submit feedback to Voxos

Sensitive Permissions

Some permissions are off by default because they grant elevated capabilities:

• members:invite - Allows adding new users to groups, potentially expanding access
• members:remove - Allows removing users from groups, which could disrupt team access
• feedback - Allows the user of the API key to send feedback to Voxos

Permission Errors

If an API key attempts an operation it doesn't have permission for, it receives a 403 error:

Error: Permission denied: 'clinks:write' not granted for this API key.
Create a new API key with this permission enabled.

Querying Permissions

API keys can query their own permissions using the get_my_permissions MCP tool or the GET /api-keys/me/permissions endpoint. This is useful for agents to understand their capabilities before attempting operations.

Creating API Keys

1. Go to API Keys in the dashboard
2. Click Create API Key
3. Enter a descriptive name (e.g., "MacBook Dev", "GitHub Actions", "Skynet")
4. Choose the scope:
   • User scope for access to all your groups
   • Group scope and select the specific target group
5. Configure permissions - most are enabled by default, but sensitive ones like members:invite and members:remove require explicit enabling
6. Click Create
7. Copy the key immediately - you won't see it again!

Managing Keys

Viewing Keys

The API Keys page shows all your active keys with:

• Key name
• Key prefix (first 12 characters)
• Scope (User-wide or specific group name)
• Creation date
• Last used date

Revoking Keys

Click Revoke next to any key to immediately invalidate it. This action:

• Takes effect immediately
• Cannot be undone
• Stops all integrations using that key

Best Practices

Naming Convention

Use descriptive names that identify the machine or purpose:

• "MacBook Pro - Personal"
• "GitHub Actions - Deploy"
• "Jenkins CI - Backend Tests"

Key Rotation

Periodically rotate keys for security:

1. Create a new key with the same scope
2. Update your configuration to use the new key
3. Verify the new key works
4. Revoke the old key

Scope Selection

Follow the principle of least privilege:

• Use group-scoped keys whenever possible
• Only use user-scoped keys when you personally need access across all your organization's groups

Secure Storage

• Never commit API keys to version control
• Use environment variables or secrets managers
• For CI/CD, use your platform's secrets feature (GitHub Secrets, GitLab CI Variables, etc.)

Scope Errors

If you use a group-scoped key to access a different group, you'll see:

Error: This API key is scoped to a specific group and cannot access group 'prod-ops'

Solutions:

• Create a new key scoped to the target group
• Use a user-scoped key if you need access to multiple groups

Key Limits

The number of API keys you can create depends on your plan:

Plan	Max Keys
Free	2
Starter	10
Pro	50
Team	200
Enterprise	Unlimited

Example Configurations

Claude Code (User-Scoped)

{
  "mcpServers": {
    "clink": {
      "command": "npx",
      "args": ["-y", "@voxos-ai/clink-mcp-server"],
      "env": {
        "CLINK_API_KEY": "sk_live_u_your_key_here"
      }
    }
  }
}

GitHub Actions (Group-Scoped)

- name: Notify team
  env:
    CLINK_API_KEY: ${{ secrets.CLINK_API_KEY }}
  run: |
    # Key is scoped to 'deployments' group only
    npx @voxos-ai/clink-mcp-server send_clink \
      --group deployments \
      --content "Deploy complete: ${{ github.sha }}"