Any AI agent can create an account for a human, then use the whole API.

ChatGPT, Codex, Claude Code, Cursor, custom agents and bots can create a provisional Fikra API account for a human, create API keys, call chat completions, read usage, check balance and top up. The agent gets a 6-hour delegated token. A claim link lets the human turn the account into a full account they control.

No signup credit on agent-created accounts. The agent must top up before chat works. This is deliberate, to stop credit farming and unsolicited accounts.

1. Create the provisional account

curl -X POST https://api.fikraapi.co.ke/v1/agents/accounts \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "agent_name": "my-agent",
    "agent_version": "1.0",
    "idempotency_key": "one-per-request"
  }'

The response contains account_id, a 6-hour token, and a claim_url. Give the claim URL to the human. Do not email it yourself unless the human asked you to.

2. Use the delegated token

Authorization: Bearer <agent token>

Scopes: keys:read, keys:write, chat:write, usage:read, balance:read, topup:link, topup:charge.

Endpoint	What it does
`GET /v1/agents/me`	Account, scopes, balance and token expiry
`POST /v1/agents/keys`	Create an API key, returned once
`GET /v1/agents/keys`	List keys without secrets
`POST /v1/agents/keys/{id}/revoke`	Revoke a key
`GET /v1/agents/balance`	Wallet balance
`GET /v1/agents/usage`	Recent usage and totals
`POST /v1/agents/topup`	Checkout link, or saved-card charge with `auto: true`
`GET /v1/agents/topup/{reference}`	Payment status
`POST /v1/agents/token/refresh`	New 6-hour token after the human claims the account

For chat, create an API key and call POST /v1/chat/completions exactly like a normal Fikra key.

3. Payments

Agents never handle card numbers. Two safe modes:

Checkout link: POST /v1/agents/topup {"amount_usd": 20} returns a Paystack URL. Send it to the human. They pay in the browser.
Saved-card charge: after the human claims the account and saves a card, {"amount_usd": 20, "auto": true} charges the saved card up to $100 per day. Anything above that needs the human to pay a checkout link.

Auto-recharge is not available to agents. It is a human dashboard setting. No card data is ever stored in Fikra logs or returned to the agent.

4. The human claim link

The agent sends the claim_url to the human. The human sets a password and the account becomes a normal full account. The link is valid for 30 days. The agent token still expires after 6 hours; after a claim, the agent can call POST /v1/agents/token/refresh.

If the human never claims, the account stays dormant with zero balance. Top-ups made before a claim remain on that account and can be claimed with the same link.

5. Safety rules

No free signup credit for agent-created accounts.
DNS and disposable-domain checks, per-IP and per-domain limits apply.
Max 3 agent-created accounts per IP per day.
Delegated tokens cannot change email or password, cannot delete the account, cannot access admin, and cannot enable auto-recharge.
Every agent action is audited with actor, action, target, amount and timestamp. Prompts and card data are never logged.
Payments are idempotent by reference. A duplicate webhook cannot double-credit.

Machine-readable spec: /agents.json. Questions: [email protected].