Courier company · Settings

Firm API key

Create a firm API key to connect your own software (ERP, accounting, call center) to Courino, choose its scopes, store it safely and revoke it.

A firm API key is a secret password that lets your firm's own software (ERP, accounting program, call center, your own reporting tool) read and act on your orders, customers and couriers in Courino. You create the key and give it to your developer; the software adds it to every request.

Only the firm owner sees this tab. Manager, operator and accountant accounts don't have it, and it can't be opened in an Albiferro support session.

Your customers have a separate key for their own software: they create it themselves in the portal. Details: Customer card. This article covers your firm's own key.

Creating a key

In the left menu, click Administration › Settings.
Choose the API keys tab at the top.
Click New key at the top right.
In Key name, write where the key will be used (e.g. "ERP" or "Accounting"). The name helps you tell later which key belongs to what.
In the Scopes list, tick what the software needs (explained below).
Optionally choose an Expiry date. At the end of that day the key stops working by itself. If left blank, it works until you revoke it.
Click Create key.
The key starting with kosk_ appears in the green box. Click Copy to take it.

The key is shown only once. After you close the box or leave the page you can't see it again. If you lose it, revoke the old one and create a new key.

Choosing scopes

Scopes decide what the key can do. The key acts on your behalf, but only within the scopes you choose. Don't choose more than the software really needs: if the key ever falls into someone else's hands, the damage stays limited to that.

Scope	What it can do
Read orders (`orders:read`)	Order list and details, history, export, attachments, tracking link
Create orders (`orders:create`)	Create new orders and get price quotes
Manage orders (`orders:manage`)	Edit, cancel, assign to / unassign from a courier, approve / reject
Read customers (`customers:read`)	Customer list, customer cards and contacts
Manage customers (`customers:manage`)	Create and edit customers
Read couriers (`couriers:read`)	Courier list, courier cards and live locations
Read pricing (`pricing:read`)	Districts, delivery types, price lists and price quotes
Read accounts and earnings (`billing:read`)	Customer accounts, payments received, charges and monthly courier earnings

Examples:

For an accounting program that only pulls reports, Read orders and Read accounts and earnings are enough.
For a call center that enters phone orders from its own screen, choose Create orders, Read pricing and Read customers.

With no scope can the key touch settings, users, passwords, payments or subscription fees. You can't change a key's scopes later; if you need different scopes, create a new key and revoke the old one.

Storing the key safely

Give the key to your developer through a password manager or an encrypted channel. Don't paste it in plain text into e-mail, WhatsApp or a message.
Don't put the key in your website's page code or in a phone app; keep it on the server only.
Create a separate key for each piece of software. Then revoking one leaves the others working.
You can have at most 5 active keys at once. Revoke one you don't use to make room.
The list shows each key's name, its last 8 characters (e.g. kosk_…Xk3p9QaZ), scopes, who created it, and when it was created, last used and expires. Revoke a key that is never used or is used at unexpected times.

Revoking a key

Open the Settings › API keys tab.
Find the key in the list by its name and last characters.
Click Revoke at the end of the row and confirm.

The key stops working within 30 seconds and shows as revoked in the list. Revoking cannot be undone.

From your phone

You can also manage keys from the Courino app (firm owner only):

Tap the Profile tab in the app.
In the Account section, open API keys.
See the list, create a new key or revoke one. A new key is shown only once here too.

When the password changes

When the firm owner's password changes, all firm API keys are revoked: when you change it yourself or reset it with Forgot my password. This makes sure the keys of an account whose password was stolen are closed too. After a password change, create a new key and give it to your developer.

The keys also stop working if your account is deactivated or ownership of the firm is transferred to someone else. The new owner must create their own keys.

What your developer needs to know

All addresses are under https://admin.courino.com/api/v1.
The key is sent with every request in the Authorization: Bearer kosk_… header.
Example request (lists orders, needs the Read orders scope): curl https://admin.courino.com/api/v1/orders -H "Authorization: Bearer kosk_…"
At most 120 requests per minute can be sent with one key. Above the limit the response is 429; wait as long as the Retry-After value in the response.
An action outside the key's scopes returns 403.
The API docs button at the top right of the tab opens documentation that describes every endpoint and can be tried in the browser (client.courino.com/api/docs). General information: courino.com/gelistiriciler.

Having trouble?

The API keys tab is missing: Only the firm owner sees this tab. If you signed in with a manager account, ask the firm owner.
I forgot to copy the key: The key is not shown again. Revoke the old one and create a new key.
The integration suddenly stopped working: Your password may have changed, the key may have been revoked or its expiry date may have passed. If the list says revoked or expired, create a new key.
The New key button is disabled: You have 5 active keys. Revoke one you don't use.
The developer gets a "403" error: The key doesn't have the scope for that action. Create a new key with the right scopes.
The developer gets a "429" error: The limit of 120 requests per minute was exceeded. The software should slow down its requests.