Agents for humans

An AI agent, bot, or chat app can create a Fikra API account for a human, use the API with a delegated token, and top it up. This is for ChatGPT, Codex, Claude Code, Cursor, custom agents and terminal tools that need to set up model access for a person. Agents do not get their own accounts here.

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

1. Create the provisional account

POST https://api.fikraapi.co.ke/v1/agents/accounts
Content-Type: application/json

{"email":"[email protected]","agent_name":"my-agent","agent_version":"1.0","idempotency_key":"one-per-request"}

The response contains an account_id, a 6-hour token, and a claim_url. Give the claim URL to the human. The account is provisional until they claim it.

2. Use the delegated token

Send Authorization: Bearer <agent token> to these endpoints.

Endpoint	Purpose
`GET /v1/agents/me`	Account, scopes, balance, 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 a key with POST /v1/agents/keys and call POST /v1/chat/completions exactly like a normal Fikra key. The delegated token is not accepted on the dashboard.

3. Payments

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 server-side. The default cap is $100 per day. Above that, use a checkout link.
Auto-recharge is not available to agents. It is a human dashboard setting.
Agents never see card numbers. Fikra stores only the Paystack authorization code on the server, never in logs or the terminal.

4. The human claim link

The agent sends the claim_url to the human. The human sets a password and the account becomes a full account. The link is valid for 30 days. The 6-hour agent token still expires; 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. Limits and safety

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

Full walkthrough: fikraapi.co.ke/for-agents. Machine-readable: /agents.json. Contact: [email protected].