Theme
Your server
Your server is the only place that holds your API key. It calls the integration API for your app, and it hands each grant to the app.
"Your server" means any place where your code runs and your members cannot read it. A server function of your backend service is such a place. An app is not: anyone can take a key out of an app.
The API reference has every call with its fields, its replies and its error codes.
Sign in
Send your API key as a bearer token with each request.
http
Authorization: Bearer cbx_test_your_key- Every address starts with
https://api.clevibox.ro/integration/v1. - A test key starts with
cbx_test_, and it sees only test clubs. - A live key starts with
cbx_live_, and it sees only live clubs. - Keep the key out of your app, out of your repository and out of your logs.
Name your members
You name a member with member_id, your own ID for that person. The first claim of a member ID creates the member, so no call registers a member.
- The ID has 1 to 64 characters.
- It must stay the same for a member.
- It must not be a name, a phone number or an email address. Use an ID that means nothing outside your system.
The calls of one visit
A member comes to the club, takes a compartment, opens it a few times, and leaves.
1. Show the compartments
GET /clubs lists your clubs. GET /clubs/{club_id}/lockers lists the lockers of one club, each with its compartments.
- A member can claim a compartment with the status
available. - With
?member_id=in the address, the compartment that this member holds hasmine: true. - Your app shows the labels, and the member picks one. The label is what the member sees on the door.
2. Claim a compartment
POST /rentals gives the compartment to the member. The reply has the rental and its first grant.
json
{
"member_id": "m-48213",
"compartment_id": "d955ef4d-f6a0-4f22-a875-91028b69339c"
}- A member holds one compartment at a time. A second claim fails with
member_has_active_rental, anddetailsnames the rental that the member holds. - Another member can be faster. Then the claim fails with
compartment_unavailable. Show the list again. - A repeat of the same claim is safe. It returns the same rental and a new grant.
3. Get a grant for each opening
POST /rentals/{id}/grants returns a new grant for the member who holds the rental. Call it each time the member taps Open.
- One grant opens the door once. A second opening needs a new grant.
- A grant lives 2 minutes. So ask for it when the member taps, and not before.
- Return
grant.tokento your app, and hand it to the SDK there. Do not store it, and do not log it.
4. Release the compartment
POST /rentals/{id}/release ends the rental and frees the compartment for the next member.
- With the reason
member, the call needs themember_idof the member who holds the rental. - With the reason
staff, your staff or your own system end the rental, for example when the member checks out of the club. - A release does not move the latch. Ask the member to take everything out first.
- A release of an ended rental returns
200and changes nothing. So a repeat is safe.
The daily auto-release
Each club has an auto_release_time in its own time zone. At that time, every active rental of the club ends, with the end_reason auto_release. Items that a member left inside stay behind a locked door until your staff open it. See Site requirements.
Find the rental of a member
GET /rentals with ?member_id= and status=active returns a list with the rental that the member holds now, or an empty list.
One route for your app
Most apps need one route on your server: "give me a grant for my locker". This example in JavaScript claims a compartment at the first opening, and it asks for a new grant at each later one.
js
const API = 'https://api.clevibox.ro/integration/v1';
async function clevibox(method, path, body) {
const response = await fetch(API + path, {
method,
headers: {
Authorization: `Bearer ${process.env.CLEVIBOX_API_KEY}`,
'Content-Type': 'application/json',
},
body: body ? JSON.stringify(body) : undefined,
});
const json = await response.json().catch(() => ({}));
if (!response.ok) {
throw Object.assign(new Error(json.message), {
status: response.status,
code: json.error,
details: json.details,
});
}
return json;
}
/**
* The grant for one opening. `memberId` comes from your sign-in session.
* `compartmentId` is the compartment that the member picked.
*/
async function grantForOpening(memberId, compartmentId) {
const query = `member_id=${encodeURIComponent(memberId)}&status=active`;
const [rental] = await clevibox('GET', `/rentals?${query}`);
if (rental) {
const { grant } = await clevibox('POST', `/rentals/${rental.id}/grants`, {
member_id: memberId,
});
return grant.token;
}
const { grant } = await clevibox('POST', '/rentals', {
member_id: memberId,
compartment_id: compartmentId,
});
return grant.token;
}Rules for your server
- Take the member from your own sign-in session. Never take the member ID from the body of the app's request. With an ID from the app, one member can ask for the grant of another member.
- Decide who may use which club. The API gives a compartment to any member ID that your server sends. Your own rules say if this member may use this club now.
- Ignore the fields that you do not know. Clevibox adds fields to a reply without a new version.
- Read each time as UTC. The times are in ISO 8601.
- Stay below 600 requests a minute for one key. Above that, a call fails with the status
429and the coderate_limited. The headerRetry-Afterhas the seconds to wait. - Test the code of an error, not its text. See Error codes.
