---
title: Agent accounts
description: Create an Appside account from your AI agent, submit listings and build a draft, then claim it by email.
---
# Agent accounts

Your AI agent can create an Appside account without a human filling a form. It can submit and claim MCP listings, submit Index entries, register apps, and build a store draft. A human claims the account before publishing or enabling payments.

## Create an account

```sh
curl https://app.appside.build/api/agent/accounts \
  -H 'Content-Type: application/json' \
  -d '{"agent":"My coding assistant","purpose":"mcp-directory"}'
```

The response contains `accountId`, `tenantId`, `token`, `claimUrl`, `expiresAt`, and `scopes`. Save the bearer token in your agent's secret storage: it is returned only once and stored hashed. Never put it in a public repository, listing, prompt transcript, or log. An optional `email` sends the human a claim link when email delivery is configured; it is never required. `claimEmailSent` reports delivery acceptance.

Use `Authorization: Bearer YOUR_TOKEN` for subsequent API requests. No browser session or Origin header is required. An account that proves control of an MCP listing's domain is kept with no human step: the domain proof is its identity. Other accounts that remain unclaimed are deleted after 30 days with their drafts and submissions; handshake-verified directory listings they submitted stay listed, unowned. Cleanup runs hourly and before account creation or agent authentication.

## Scopes

| Scope | Before claim | After verified claim |
| --- | --- | --- |
| mcp-directory:write | Submit, request domain proof, confirm, edit and remove owned listings | Same domain proof required |
| index:submit | Submit for editorial review | Submit for editorial review |
| catalog:write | Register and verify apps using domain proof | Register and verify apps |
| store:draft | One starter tenant, draft edits, one AI generation per day, deterministic preview | Normal publisher permissions |
| Live actions | Publishing, rollback, payments, onboarding, payouts, team invites, email changes and live API keys return 403 with the claim URL | Full rights of the claimed publisher |

Other publisher operations are denied before claim. An account alone never proves domain ownership or causes an Index entry to publish.

## Use MCP

Connect to `https://appside.build/mcp`, or run `npx appside-mcp` for stdio. Call these tools in order:

```json
{"name":"create_account","arguments":{"agent":"My coding assistant","purpose":"mcp-directory"}}
```

```json
{"name":"submit_mcp_server","arguments":{"token":"YOUR_TOKEN","server":{"name":"My server","url":"https://example.com/mcp","site":"https://example.com","category":"Developer Tools","auth":"Open"}}}
```

```json
{"name":"claim_mcp_listing","arguments":{"token":"YOUR_TOKEN","slug":"my-server"}}
```

Publish the returned domain-proof token at the returned `.well-known` URL. This is a separate verification token, not your account bearer token. Then call:

```json
{"name":"confirm_mcp_claim","arguments":{"token":"YOUR_TOKEN","slug":"my-server"}}
```

On HTTP, an `Authorization: Bearer YOUR_TOKEN` request header can replace the `token` tool argument. Stdio uses the argument. The `submit_index_entry` tool takes `token` and an `entry` object matching the [Index submission form](https://app.appside.build/index-submit). The existing `register_app` and `verify_app` tools accept an optional `token` argument or HTTP bearer header and retain their domain-proof workflow. Authenticated catalog registrations are associated with the agent account for expiry cleanup.

## Draft and directory API

```sh
curl https://app.appside.build/api/me -H "Authorization: Bearer $APPSIDE_TOKEN"
curl https://app.appside.build/api/tenants/YOUR_TENANT -H "Authorization: Bearer $APPSIDE_TOKEN"
```

Save a draft with `PUT /api/tenants/YOUR_TENANT/draft` and `{revision,store}` from the workspace response. Generate with `POST /api/tenants/YOUR_TENANT/generations` and `{name,brief}`. The deterministic preview is available at `/preview?app=APP_STORE_URL`.

Directory endpoints are `POST /api/mcp-directory`, `POST /api/mcp-directory/SLUG/claim`, `POST /api/mcp-directory/SLUG/confirm`, and `PATCH` or `DELETE /api/mcp-directory/SLUG`. Index submissions use `POST /api/index/submissions`. Catalog registration uses `POST /api/catalog/apps` and retains its own verification instructions.

## Human claim and revocation

Give the human the private `claimUrl`. They open it, choose an email and password, and enter the six-digit code delivered through Appside's email verification flow. Verification converts the original account: the same user, tenant, submissions and domain claims remain. The link becomes unusable after conversion. An email already registered with Appside cannot claim another account through this flow.

The agent token continues working with that publisher's full rights. In Studio, open **Settings → Agent tokens → Show agent tokens → Revoke** to end its access. Tokens are never displayed again.

## Limits

Account creation is limited to 5 per IP per hour, 20 per IP per day and 500 globally per day. Limits persist across restarts. Each token has a bucket of 60 calls, refilling at one call per second. Existing directory, catalog and publisher limits also apply. Unclaimed accounts have one tenant and at most one AI generation request per UTC day; the existing per-run and platform AI budgets still apply. Denied or invalid generation attempts may consume the daily request allowance. HTTP 429 indicates a limit.