Applications with Api access#
The Api is the website's entry point for programs: your mobile app, or a partner's system that takes listings, products or orders from the website. Every such application must identify itself with an application key in every request. You issue and manage the keys on this screen. An application can have several keys and each can have a date when it stops working — so you can replace a key without an outage.
You will find the screen under Settings → Applications with Api access (the Settings link at the very bottom of the left column, see Settings). Only an administrator sees it.
What the application key does#
- The key only says that the application may call the Api. Without a valid key the Api refuses the application.
- What data the application gets depends on the rights of the user logged in inside it — the same as on the website. When nobody is logged in, the application sees only what a website visitor sees.
- The website and the administration do not need a key. The key is only for programs outside the website.
- For each application you set how many requests it may send and which user roles may be used through it.
Who needs the key
The key belongs to a program, not to a person. Website visitors and administrators never enter it. You hand it over once to the application's developer, who puts it into the application or on their server.
Application list#
The table shows for each application:
| Column | Meaning |
|---|---|
| Name | the name you gave the application |
| Keys | how many valid keys the application has, e.g. 2 valid. After a dot you see how many keys expire soon (with the date), how many have expired and how many are revoked (in grey) |
| State | Active, Disabled or Revoked |
| Per second, Per minute | how many requests the whole application may send; default (20) means the website default applies |
| Allowed roles | roles that may be used through the application. A role with extended rights (e.g. Administrator) is highlighted |
| Last used | when the application last sent a request (recorded at most once a minute) |
| Created | when you created the application |
Buttons in the row: edit, Keys (the application's keys page), Disable / Enable and Revoke. A revoked application keeps only Keys — you can delete expired and revoked keys there.
Creating an application#
- Click add above the table.
- Fill in a Name that identifies the application (e.g. “Mobile app” or the partner's name). The Note is just for you — who runs the application, a contact, etc.
- Leave the limits empty unless you know the application needs different ones (see Request limits).
- Check the Allowed roles (see Allowed roles). The roles of ordinary users are pre-ticked.
- In the First key part you can give the key a Label (e.g. “version 2.1”) and a Valid until date. Both are optional — an empty Valid until means the key works until you revoke it.
- Click Save.
After saving you return to the list and see the application key at the top.
Storing the key#
The key is shown only once — right after creating the application (in the list) or issuing another key (on the Keys page). The website does not store it, it keeps only its hash, so it can never show it again.
- Click Copy next to the key (or select the key in the field and copy it).
- Store it right away in a safe place (a password manager) or hand it to the application's developer.
- Only then leave the page. After a reload you will see only the beginning of the key (its first 16 characters) on the Keys page.
Send the key securely
Do not send the key by ordinary e-mail or in a chat where it stays stored. Whoever has the key can call the Api on behalf of your application. If you lose the key or suspect it has leaked, issue a new key and revoke the old one.
The application sends the key in the X-API-Key header with every request. Details for
developers are in Authentication.
Request limits#
Limits protect the website from overload. When the application exceeds them, it gets a “too many requests” error saying how long to wait before trying again. Each limit is a whole number from 1 to 1,000,000; an empty field means the website default, which is written right in the field.
| Field | What it limits | Default |
|---|---|---|
| Whole application per second | all requests of the application together in one second (peaks) | 20 |
| Whole application per minute | all requests of the application together per minute (sustained load) | 600 |
| Logged-in user per minute | requests of one logged-in user of the application | 120 |
| One address per minute | requests of a user who is not logged in, from one address | 120 |
Limits take effect as soon as you save.
Your own mobile app needs more
All users of an application share its overall limit. Many people may use your mobile app at the same time, so give it higher limits than a single partner's application. The per-address limit may also be too low where many people share one address (a mobile operator, a company).
Allowed roles#
Only the ticked roles apply through the application. If the logged-in user has another role as well, the application treats them as if they did not have it. For example, an administrator who logs in to a partner's application without the Administrator role allowed gets only what an ordinary signed-in user gets.
The Guest role is mandatory: it is always ticked and cannot be unticked. Calls without a sign-in and signing in itself are evaluated with this role — without it nobody could even sign in to the application.
A new application has these pre-ticked:
| Role | Why |
|---|---|
| Guest (mandatory) | without a sign-in the application sees what a website visitor sees; users sign in through this role |
| Signed-in user | a signed-in user sees what they see on the website |
| Owner | the user can edit their own records (e.g. their own listing) |
| Receiver | the user can read what is meant for them (e.g. responses to their listing) |
Roles with extended rights carry the extended rights label and the warning “A user with this role will be able to manage the website through the application.” Tick them only for an application you fully trust — typically your own application for managing the website, never a partner's application.
An application for public data only
If you untick every role except the mandatory Guest, the application gets only what a website visitor sees, even when someone signs in to it.
Editing an application#
Click edit next to the application, change the name, note, limits or allowed roles and click Save (back to the list) or Apply (stay in the form). Changes take effect immediately. The keys do not change — you manage them on the Keys page. If you clear a limit, it goes back to the default.
Disabling an application#
Click Disable. From that moment all keys of the application are refused — the application gets the same error as if it had sent no key. Disabling can be undone — Enable lets the application in again and its valid keys work again. Use it when you need to stop an application for a while, for example because of suspicious traffic.
Application keys#
An application can have several keys. Each key can have a date and time when it stops working (Valid until). This lets you replace a key without an outage: the new version of the application gets a new key and the old version keeps running with the original key until that key expires. This is useful above all for a mobile app, where approval of a new version in the app store can take several days.
Open the page with the Keys button in the application's row. For each key you see the key prefix, the label, when it was created, until when it is valid, when it was last used and its state:
| State | Meaning |
|---|---|
| Valid | the key works |
| Expires soon | the key works but expires within 7 days — the Valid until column also shows the number of days |
| Expired | the Valid until date has passed; the application gets an error with this key (the row is grey) |
| Revoked | you revoked the key; the application gets an error with it (the row is grey) |
Request limits belong to the whole application, not to single keys — all keys of the application share them.
New key#
- On the Keys page click New key.
- Fill in a Label (optional, e.g. “version 2.1” or “partner server”) and, if needed, Valid until. An empty Valid until means the key works until you revoke it.
- Click Save. The new key is shown only once at the top of the keys page — store it the same way as when creating the application.
The other keys of the application keep working. An application can have at most 5 valid keys (expired and revoked keys do not count). When it has five, the New key button is inactive — revoke a key first or wait until one expires.
Editing a key#
Edit changes the label and the Valid until date. You can set the date on a key that did not have one, move it, or clear it — the key then works until you revoke it. The date must be in the future. The change takes effect immediately. A revoked key cannot be edited.
Replacing a key without an outage#
- Set Valid until on the old key — the date until which the old version of the application will still run.
- Issue a new key.
- Deploy the new key in the application (for a mobile app, a new version).
- After the Valid until date, delete the old key.
Revoking a key#
Click Revoke next to the key and confirm with Revoke key. The key stops working at once and revoking cannot be undone; the other keys of the application keep working. Revoke a key that has leaked or been lost. If the key should stop working only later, set Valid until instead.
Deleting a key#
Delete an expired or revoked key with Delete — it disappears from the list. A valid key cannot be deleted; revoke it first.
Revoking an application#
Click Revoke and confirm with Revoke permanently. All keys of the application stop working at once.
Revoking is final: a revoked application can no longer be enabled, edited or given a new key. The application is not deleted — it stays in the list with the Revoked state so you know it existed. To stop it only for a while, use Disabling.
Permissions#
Only the Administrator role has the screen and all its actions. Each action has its own permission (view, create, edit including enable and disable, revoke the application, keys page, new key, edit key, revoke key, delete key), so they can be assigned differently under Users and roles.