---
title: "Keys"
description: "One person, one organization, a role and an expiry."
canonical: "https://poddub.com/docs/agents/keys"
last-updated: "2026-10-29"
---

# Keys

One person, one organization, a role and an expiry.

An agent connects to poddub in one of two ways, and this page is about the second.

## Signing in or a key

* **Signing in** is for a person using an agent: claude.ai or Claude Code sends you to poddub.com, you sign in with your own poddub account, choose the organization, and allow the agent with the most it may do, Member unless you choose more and never above your own role. Anyone in an organization can. See [Connect claude.ai](/docs/agents/claude-ai) and [Connect Claude Code](/docs/agents/claude-code).
* **A key** is for work that runs without a person, such as a script or an automation, and for an agent that cannot sign in, such as Cursor. Only an owner makes keys.

Either way, the agent never does more than its person can. A connection made by signing in stops when you end it on poddub.com/connections, the page called **Connected agents**, when you leave or are removed from the organization, when the organization is deleted, and when your poddub account is deleted.

The rest of this page is about keys. A key says who the agent works for, where, and how far.

## What a key is

A key:

* belongs to the owner who made it, and the agent acts as that person;
* works in one organization, the one it was made in;
* has a highest role, owner, admin or member, so the agent never does more than that role allows, nor more than its person can do today;
* stops working after 90 days unless another length was chosen, from 1 to 365 days.

The role is checked again on every call. If the person's own role drops below the key's highest role, the agent drops with it at once.

## Making a key

An owner makes a key in the poddub app:

1. Open **Manage**, then **Agents**.
2. Under **New key**, give it a **Name**, choose its **Highest role**, and fill in **Days until it stops working**: from 1 to 365, or leave it empty for 90.
3. Tap **Make key**.

The key is shown once. Tap **Copy key** and keep it as you would a password: in an environment variable or a password manager, never in a file you commit, a chat or a ticket.

A key is always its maker's own: an owner makes keys only for themselves, and an agent that holds one acts as that owner, never above the highest role chosen. Only owners see **Agents**. An owner who does not see it updates the app.

## What stops a key

A key stops working:

* when it expires;
* when it is revoked;
* when its person leaves or is removed from the organization;
* when the organization is deleted;
* when its person's poddub account is deleted.

A call with a key that stopped is refused before it reaches any tool, with `expired_api_key`, `revoked_api_key` or `invalid_api_key`. An expired key is reported as expired once; after that it reads as unknown. The agent cannot make itself a new key: the owner it belongs to makes a new one in the app and puts it where the old one was.

## Seeing and revoking keys

In **Manage**, then **Agents**, an owner sees every key of the organization, with who made it and when it was last used, and can revoke any of them. Revoking takes effect on the next call. A revoked key stays in the list, marked revoked, and cannot be turned back on.