Agents

An agent is its own account, owned by a person, holding an explicit subset of that person’s permissions. With apps.manage it can register and manage that person’s apps through the agent API.

Get a Key

An agent cannot make its own key. A person makes it:

Aiden, or someone Aiden has given agents.manage, creates an agent in Account Settings and ticks apps.manage. The person must hold apps.manage themselves; Aiden holds every permission.
They create a key for the agent and give it to the agent as a secret. It looks like ktk_XXXXXXXX_<43 characters> and expires after 90 days by default (1 to 365 days).

An agent can also ask for access with a code a person approves (the RFC 8628 shape): it calls POST /api/agent/device/code, a person enters the code at accounts.aidenkt.com/agents/approve, and the agent polls POST /api/agent/device/token. The result is the same: a key.

Keep the key out of logs, URLs and prompts. Send it only to https://accounts.aidenkt.com/api/agent/token.

Exchange the Key for an Access Token

curl -s -X POST https://accounts.aidenkt.com/api/agent/token -H "Authorization: Bearer $KT_AGENT_KEY"

{ "access_token": "kta_…", "token_type": "Bearer", "expires_in": 3600, "scope": "apps.manage" }

The access token lasts 1 hour. Exchange the key again when it expires (401 invalid_token). Use the access token, never the key, on every other call.

Check the Token

curl -s https://accounts.aidenkt.com/api/agent/whoami -H "Authorization: Bearer $TOKEN"

{ "kind": "agent", "id": "…", "name": "Builder", "ownerUserId": "…", "permissions": ["apps.manage"],
  "owner": { "isOwner": false, "roles": ["developer"] }, "via": { "method": "key" } }

permissions is what the agent may do right now: its own list, narrowed to what its person currently holds. Agents never inherit Aiden’s “all”. owner says whether the agent’s person is Aiden and lists that person’s roles (badge keys), and nothing else about them.

A server that receives requests from an agent can check it the same way: call this endpoint with the access token the agent presented. 401 invalid_token means it is not a live token.

What an Agent Can Do

With apps.manage, everything a developer can do in the portal, for its person’s apps:

list, register, read, change and delete apps;
rotate client secrets;
set and remove icons, including icons from the icon maker’s pack.

The full reference, with a curl example for every endpoint, is in Agent API and Errors (for Developers and above), and in the canonical agent guide (public).

What an Agent Cannot Do

Read people’s data: there is no agent endpoint for consents, in-app identities or users.
See or change anyone else’s apps, or the three built-in apps.
Suspend or resume an app, or reorder Your Apps. These are Aiden’s alone, in person.
Give itself permissions or badges.

Revoking a key, disabling the agent, removing a permission from its person, or deleting the person takes effect on the next call.

Reading Restricted Pages Here

Some pages on this site need a level. An agent reads them by sending its access token:

curl -s https://docs.aidenkt.com/agents/api.md -H "Authorization: Bearer $TOKEN"

See Access to These Docs.