Sika

Developers

Build on Sika

Programs you write can read Sika's public spaces and, through a bot, post in public channels. Private chats, files and calls can never be reached: they are end to end encrypted and our servers hold no keys to them.

Building for a company that needs seats, an audit trail and a named contact? See Sika for companies.

What you can do

Read public channels. Channels, their posts, halls and forums are public. Anyone can read them without an account or a key, and every post is signed by the Sika key that wrote it, so you can check who wrote what.

Post as a bot. A bot has a Sika key of its own. A channel owner names the bot as an admin of the channel, and then your program can post text there. Posts by a bot are public and marked Bot in the app.

What is not possible. A bot cannot join, read or write a private chat or a group. There is no endpoint that lists a person's followers or members. This is not a setting we may change later: it follows from how Sika is built.

Get a key

Open Sika, then Settings, Developers. Create a key and copy it at once: it is shown only one time, and we keep only a scrambled fingerprint of it. A lost key is revoked and replaced, never recovered. Revoking a key stops it at once.

Keep a key like a password. Never put it in an app you give to other people or in a web page.

Make a bot

  1. In Settings, Developers, create a bot and give it a name people will recognise.
  2. Copy the bot's Sika key (64 characters) and give it to the owner of the channel.
  3. The owner opens the channel settings, taps Add a bot by its key, pastes it and saves. The bot is now an admin of that channel and can post there. It cannot change the channel.
  4. Deleting a bot stops it posting at once. The posts it already made stay.

Bots in halls

A bot can also take part in the forum of a public hall. It joins the hall first, like any member, and then starts topics and answers them. The hall's elders can lock a topic or remove a bot's post, and an upheld report freezes the bot, as in channels.

POST /v1/bots/BOT_ID/halls    {"hall": "HALL_ID"}
POST /v1/bots/BOT_ID/topics   {"hall": "HALL_ID", "title": "Market prices today", "text": "Tomatoes 500 a basket"}
POST /v1/bots/BOT_ID/replies  {"topic": "TOPIC_ID", "text": "Thanks, noted."}

Topics and replies count towards the bot's posts for the day. A refused call answers 422 with the reason, such as join_first (the bot has not joined the hall) or locked.

Business Messaging

Order updates, delivery alerts and login codes to customers who agreed to them, with templates Sika reviews. Not open yet. Read how it will work on Business Messaging.

Using the API

Send your key as a bearer token. The service address is shown in Settings, Developers.

curl -H "Authorization: Bearer sika_live_YOUR_KEY" https://DEV_HOST/v1/whoami

This answers with your key, your account, your plan, its limits and today's use. To post as a bot:

curl -X POST https://DEV_HOST/v1/bots/BOT_ID/posts \
  -H "Authorization: Bearer sika_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "CHANNEL_ID", "text": "Rain expected in Accra this afternoon."}'

A post is text up to 4,000 characters. A successful post answers 201 with its id. If the channel does not name your bot as an admin, the answer is 422 with not_an_admin.

Webhooks

On Builder and Business, Sika can tell your server when something happens in a public channel your bot administers. In Settings, Developers, set an address for the bot. It must be an https address on the public internet: addresses that point inside a network (such as localhost or 10.x.x.x) are refused, and so are addresses with a login in them or an unusual port.

Three kinds of event exist: post.created (someone else posted in the channel), reaction.added (the emoji and the totals, never who reacted) and channel.followed (the new follower count, never who followed). Each carries only what is already public. A bot is not told about its own posts.

Every delivery is a POST with a JSON body and these headers: Sika-Event (the kind), Sika-Delivery (a unique id, so you can ignore a repeat) and Sika-Signature, which proves the message came from Sika and was not changed or replayed. Check it before you trust a message. The developer library, which key holders can download, does the check for you (see Quick start); its source shows the exact scheme for any other language.

The signing secret (it starts with whsec_) is shown once, when you save the address, and can be replaced with a new one at any time. Answer with any 2xx status within a few seconds. If you do not, Sika tries again several times over about a day, then gives up on that event. If many events in a row are given up, the webhook is switched off until you save its address again. Use Send a test event to check your address and your signature check.

Quick start

Make a key in the Sika app (Settings, then Developers). Tick only what the key needs: Post as a bot, Read deals, Make and manage deals or Set the deal webhook. A key that leaks can then do only that. The library is one file with no dependencies, for Node 18 or later. It is for key holders only: download it with your key.

curl -H "Authorization: Bearer sika_live_YOUR_KEY" https://DEV_HOST/v1/sdk/sika-dev.mjs -o sika-dev.mjs
import { SikaDev } from './sika-dev.mjs';

const sika = new SikaDev({ apiKey: process.env.SIKA_KEY });

// Take a protected payment
const { deal } = await sika.deals.create({
  amountMinor: '120000',          // 1,200.00 KES, as text
  currency: 'KES',
  description: 'Green tea 250g x 10',
  ref: 'order-1001',              // your own order number: a retry never makes a second deal
});
console.log(deal.payUrl);         // give this link to your customer

// After you hand the goods over
await sika.deals.ship(deal.id, 'DHL T123');

// Post as a bot (the channel owner must have named the bot an admin)
await sika.bots.post(BOT_ID, { channel: CHANNEL_ID, text: 'New stock today' });

Errors come as a SikaError with a status and a code. The library retries what is safe to repeat (reads, and deals that carry a ref) after a dropped connection or a brief outage, and nothing else.

Control what a key can do

Beyond permissions, every key can carry three more limits, set when you make it or later: an expiry after which it stops working, a list of addresses it may be used from (one address or an IPv4 range like 203.0.113.0/24), and a daily cap below your plan's. A leaked key is then useless anywhere else, or after its date. A key can be rotated: you get a new key with the same permissions and limits, and the old one keeps working only for the hours you choose, so a program can be switched over without a gap.

Every change made by a key or by you is written to an audit log that you can read in the app or download as a spreadsheet: who (which key, or you), what, to what, when and how it went. It is kept for 400 days. Reads and rate-limit answers are not logged, and no secret or request content is kept.

AnswerMeaning
401 key_expiredThe key passed its expiry. Rotate it or make a new one.
403 ip_not_allowedThe key has an address list and this request came from another address.

Checkout: sell with protection

Your key can take real money. Make a deal for a customer and send them the pay link. Sika holds the payment until the customer confirms delivery. The customer needs no Sika account. You are paid to the account you saved in the Sika app (Orders, then Where you are paid); you must save it before the first deal, and until you do the call answers payout_account_needed. A customer with a problem reports it from the same link and Sika's dispute process decides. The customer pays the amount plus Sika's fee; you receive the full amount.

CallKey permissionWhat it does
POST /v1/dealsMake and manage dealsMake a deal and get its pay link. Send an Idempotency-Key header (or a ref) so a retry is safe.
GET /v1/deals, GET /v1/deals/IDRead dealsList your deals (filter with ref), or read one.
POST /v1/deals/ID/shipMake and manage dealsMark it sent. Also cancel, decline (refund) and dispute.
PUT /v1/webhook and the calls beside itSet the deal webhookBuilder and Business. A signed message when a deal is paid, shipped, completed, refunded or disputed.

A deal's status is awaiting_payment, paid, shipped, completing, completed, refunding, refunded, cancelled or disputed. Its live field says whether real money is used. Check a webhook with the library before you trust it:

import { verifyWebhook } from './sika-dev.mjs';

app.post('/sika-hook', express.raw({ type: '*/*' }), (req, res) => {
  const event = verifyWebhook({
    secret: process.env.SIKA_WEBHOOK_SECRET,        // whsec_..., shown once when you set the address
    signature: req.get('Sika-Signature'),
    body: req.body.toString('utf8'),                 // the raw text, exactly as received
  });
  // event.type is deal.paid, deal.shipped, deal.completed, ...; ignore a repeated Sika-Event-Id
  res.sendStatus(200);
});

A product in a post: when a channel post links a listing from the Sika market, the post shows that listing, as its seller signed it, with a Buy with protection button.

Sign in with Sika (early access)

Let people sign in to your website or app by approving on their own Sika app with their Sika key. There is no password and no code to type. To your code it is an ordinary OpenID Connect provider (OAuth 2.1 with PKCE), so any standard library works. It is being opened step by step: register an app in Settings, Developers, Apps for Sign in with Sika, and it starts in test mode, where only you and the testers you name can sign in.

What your app gets: a verified person, an identifier that is different for every app (so two apps cannot match up their users), and the name they chose to share. It never gets their messages, contacts, files or money, and there is no way to ask for them.

  1. Register your app. You get an App ID, and for a server app a secret that is shown only once. Give the website it belongs to and the exact return addresses, on your own website (https; a loopback address is allowed for a tool on a computer).
  2. Send the person to the authorize address with a PKCE challenge (S256 is required) and a state. Sika shows who is asking and a match code, and the person approves on their phone.
  3. They come back to your return address with a one-time code. Swap it, with your PKCE verifier, for an ID token, an access token (10 minutes) and, if you asked for offline access, a refresh token.

A button on any page:

<script src="https://SIGN_IN_HOST/button.js"
        data-client-id="app_YOUR_ID"
        data-redirect-uri="https://your.site/auth/sika/callback"
        data-scope="openid profile"></script>

Swap the code on your server:

curl https://SIGN_IN_HOST/token \
  -d grant_type=authorization_code -d code=$CODE -d redirect_uri=$REDIRECT \
  -d client_id=app_YOUR_ID -d code_verifier=$VERIFIER -d client_secret=$SECRET

On Android, use the standard AppAuth library with the authorize and token addresses from the discovery document at /.well-known/openid-configuration. On iPhone, use AppAuth or ASWebAuthenticationSession the same way. The sign-in address is given when it opens.

For a TV, kiosk or till that has no browser to type into, use the device flow (RFC 8628): post your App ID and scope to the device authorization address, show the person the code it returns (like BCDF-GHJK), and poll the token address with the device code. The person types the code in Sika, Connected apps, Enter a code, sees who is asking and approves. Poll no faster than the interval it gives you; asking too fast makes the interval longer.

What you may ask for: openid and profile (the name the person chooses to share), and offline_access for a refresh token. Refresh tokens rotate, last 30 days unused and six months in all, and stop at once when the person removes your app. Sika checks businesses before showing them as checked; an unchecked app is labelled plainly on the approval screen.

AI assistants (early access)

An AI assistant can connect to Sika through the Model Context Protocol (MCP). The address is https://mcp.sikaos.app/mcp (Streamable HTTP). Three tools need no sign-in and only read what is already public: shop_search (listings in the town market), listing_get (one listing) and channel_posts (recent posts of a public channel).

Two more tools work for a signed-in person, who signs in with Sika the same way as above (the authorization server is named in /.well-known/oauth-protected-resource). order_status reads the state of the person's own order and nothing else. order_create_link only asks: the request waits on the person's phone, they see exactly what it is, and nothing happens unless they approve it there. Their phone then makes the order with their own key and gives back a payment link; the assistant never holds money, a key or a chat. action_status says whether a request is waiting, approved or refused.

The tools for orders and payment links are switched on per app by Sika after a check, and are never part of a default sign-in. It was tried with the official MCP client library, not yet with a named assistant, and it is still waiting for an outside security review, so treat it as early access. Messages, contacts, files and money can not be reached through it.

Plans and limits

PlanPrice a monthKeysRequests a dayBotsPosts per bot a dayNew deals a day
FreeNothing11,00012020
BuilderNGN 5,0005100,00055002,000
BusinessNGN 50,000202,000,000505,00050,000

Builder and Business are paid a month at a time, in the app, on Flutterwave's page (card, bank transfer, USSD or mobile money). They never renew by themselves. When a paid month ends your account returns to Free. Paying for the plan you have adds a month to its end; paying for a higher plan starts it at once, and the time left on the lower one is not carried over. A lower plan cannot be bought while a higher one is running.

Errors

AnswerMeaning
401 unauthorizedThe key is missing, wrong or revoked.
429 rate_limitedToo many requests this minute. Wait 60 seconds.
429 daily_limitYour plan's requests for today are used. The count restarts at midnight UTC.
429 bot_daily_limitThis bot reached its posts for today.
403 insufficient_scopeThis key was not given the permission the call needs.
429 deal_limitYour plan's new deals for today are used. Retries count too.
402 plan_requiredWebhooks are on Builder and Business.
409 payout_account_neededSave where you are paid in the Sika app before taking payments.
409 ref_in_useThat ref was already used for a different deal.
404 not_foundNo such bot for your account.
400 invalid_inputThe body was not what the call expects.
422 with a reasonThe public service refused the post: not_an_admin, channel_hidden, too_many_posts, prohibited or bot_frozen.

Rules

Bots follow the same rules as everyone: no illegal goods, no harassment, no deception about who runs the bot. Posts by bots can be reported like any post. A bot with enough upheld reports is frozen, and a frozen bot cannot post. Do not collect people's data through a bot. Do not use a key to try to reach private chats; there is nothing there to reach.

We may change the limits and plans with notice in the app. Using the developer tools means you accept the Terms of Use.

Questions

Write to support@sikaos.app. To report a security problem, see Security.