Skip to content

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 has mine: 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, and details names 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.token to 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 the member_id of 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 200 and 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 429 and the code rate_limited. The header Retry-After has the seconds to wait.
  • Test the code of an error, not its text. See Error codes.