The clevabit API is organized around the REST principle. It features predictable resource-oriented HTTP URLs.

While all request bodies are expected in JSON encoded request objects, all responses provided by the API are encoded as CBOR objects, except stated otherwise.

The API uses standard HTTP verbs, and response codes.

This documentation is constructed using a couple of different styles.

The first paragraphs give information about basic concepts and requirements that need to be understood and followed when using the API.

The second part of the documentation contains the available operations, grouped by domain. The operations descriptions contain multiple different information in a very concise representation. The following image gives a quick overview of the information available from those specifications.

The last part of the documentation is a definition of all the objects being used for requests and responses. Those are directly being linked back and forth with the operations.

Possible API Modifiers (Tags)

Certain APIs are marked with specific tags. Those tags give additional information about the status of the API.

At the moment the following tags are defined:

• Work In Progress (WIP): This API is in specification progress. Please be aware that it may not be implemented yet or change without further notice.
• Deprecated (DEP): This API is deprecated and shouldn’t be used anymore. Please exchange code that still uses this endpoint.
• To Be Removed (TBR): This API was deprecated before and is now marked to be removed in the near future.

This documentation is updated and extended on a constant basis. Keeping informed about updates may be important, especially when it comes to deprecations or removal.

While we try to keep things backwards compatible, certain situations, e.g. security concerns, force us to make incompatible changes to the API.

To stay informed with important updates, you can join the Developer Portal Updates mailing list and automatically receive updates whenever important updates happen right into your inbox.

To sign up for being notified automatically use the form below.

The Sandbox provides demo data from testing devices, which are not related to any real world customer. That said, the Sandbox cannot access real customer data.

To login into the Sandbox, use the same application id and application key to be used against the production environment, however username/email and password are different and valid only with the sandbox environment.

Apart from that, the sandbox has one additional feature, which is not available in the production environment.

The sandbox includes support to send and receive objects as JSON. Support for this feature is implemented according to the W3C defined standard headers:

Furthermore, the Sandbox has relaxed Rate Limits, therefore is suited for development and debugging uses.

The Production environment is used for real world requests, being directed towards real customer data and objects are always encoded as CBOR with the content type application/cbor). Accept and Content-Type headers are ignored in production.

Production environments have specific Rate Limits. Therefore, development and testing should only be executed against the Sandbox environment.

After a valid login, the response contains the Authorization Token, which is used for further calls to the API. This token is also known as Bearer Token.

The Authorization Token itself is a base64 encoded and signed JSON object, called JSON WebToken.

The Bearer Token can be provided by two different ways, one more suited for web applications (especially progressive webapps), the latter one for server to server communication.

When using a HTTP client which directly supports cookies (like browsers), the authorization cookie is automatically set upon successful login.

To provide the Bearer Token as a HTTP header, a header field named Authorization with the value being a concatenated string of bearer …token…

curl -H "Authorization: Bearer ...token..."

The Authorization Token is a signed and base64 encoded JSON Webtoken. This means it can be decoded by the application, and using the correct public key, it could also be validated.

The JSON Webtoken contains a set of values which might or might not be interesting to the application. The full JWT specification is available as RFC 7519.

The clevabit API uses two types of tokes, depending on how you authorized with the API. While Auth0 provided JWT tokens (all frontend logins) check permissions based on a finer grained scope system, according to the OAuth2 / OpenId specification. Tokens retrieved through the Application login Logging In (Applications) though, use a slightly simpler access system purely based on roles, as applications can act on multiple customers (if priviledges are set).

To decode the JSON Webtoken, the signature has to be cut off and the base64 encoded data have to be decoded and parsed into a JSON data structure.

Using JavaScript, the following function, helps performing those steps.

function parseJwt(token: any): any {
    let base64Url = token.split('.')[1];
    let base64 = base64Url.replaceAll('-', '+').replaceAll('_', '/');
    return JSON.parse(window.atob(base64));
}

Values inside the JSON Webtoken:

Additionally to the standard claims described above, partner application login tokens contain an additional set of namespaced claims.

Claim namespaces for clevabit partner application tokens always begin with the namespace https://auth.clevabit.com/ appended by the actual claim’s name. That said, a namespaced claim test would actually be represented by a claim with the key https://auth.clevabit.com/test.

Available claims are:

The query language grammar is defined as the following pseudo grammar definition:

WHITESPACE: [ \r\n\t]+ -> skip ;

fragment Letter: [a-zA-Z]+ ;
fragment HexDigit: [0-9a-fA-F] ;
fragment HexOctet: HexDigit HexDigit ;
fragment OctalDigit: [0-7] ;
fragment ZeroToThree: [0-3] ;
fragment DigitNoZero: [1-9] ;
fragment Digit: '0' | DigitNoZero ;
fragment NaturalNumber: DigitNoZero Digit* ;
fragment Character: ~['"\\] | EscapeSequence ;
fragment EscapeSequence: '\\' [btnfr"'\\] | '\\' OctalDigit | '\\' OctalDigit OctalDigit | '\\' ZeroToThree OctalDigit OctalDigit ;
fragment DoubleHex: HexOctet HexOctet ;
fragment QuadHex: DoubleHex DoubleHex ;
fragment SextetHex: DoubleHex DoubleHex DoubleHex ;

MINUS: ('-') ;
GT: '>' ;
LT: '<' ;
GE: '>=' ;
LE: '<=' ;
ASSIGN: '=' ;
WILDCARD: '*' ;

IDENTIFIER: Letter (Letter | '-')* Letter ;
TERMINAL: ('"' Character* '"') | ('\'' Character* '\'') ;
FLOAT: ('0' | NaturalNumber)? '.' Digit Digit* ;
INTEGER: Digit+ ;
UUID: QuadHex '-' DoubleHex '-' DoubleHex '-' DoubleHex '-' SextetHex ;

query:
    '*'                                                 # selectAll
    | (elementRule (',' elementRule)* EOF)              # elements
;

floatRule:
    MINUS? FLOAT
;

integerRule:
    MINUS? INTEGER
;

elementRule:
    identifier=IDENTIFIER ':' predicate=predicateRule
;

uuidRule:
    uuid=UUID
;

wildcardRule:
    WILDCARD
;

stringLiteralRule:
    TERMINAL
;

predicateRule:
    listRule                                            #list
    | objectRule                                        #object
    | floatRule                                         #float
    | integerRule                                       #integer
    | uuidRule                                          #uuid
    | wildcardRule                                      #wildcard
    | stringLiteralRule                                 #string
    | comparisonRule                                    #comparison
;

listElementsRule:
    (floatRule (',' floatRule)*)                        #floats
    | (integerRule (',' integerRule)*)                  #integers
    | (uuidRule (',' uuidRule)*)                        #uuids
    | (stringLiteralRule (',' stringLiteralRule)*)      #strings
;

listRule:
    '[' listElementsRule? ']'
;

objectRule:
    '{' query '}'
;

comparisonRule:
    comp1=comparisonRule '&&' comp2=comparisonRule      #and
    | comp1=comparisonRule '||' comp2=comparisonRule    #or
    | operatorRule                                      #operator
;

operatorRule:
    op=(GT | LT | GE | LE) floatRule | integerRule
;

All data returned from the authenticated API calls is encoded in the space efficient binary data format CBOR, except stated otherwise.

CBOR is a standard for binary encoding, specified through the IETF (Internet Engineering Task Force) and available as RFC 7049. The object format of CBOR objects mostly resembles those of JSON objects, supporting objects, lists, dictionaries and properties. The main reason for using CBOR is the binary representation, variable length encoding of numeric values, as well as the easiness of encoders and decoders.

The only exception is the Sandbox environment, which can be asked to return JSON objects instead.

CBOR encoders and decoders are available for many programming languages and runtime environments. An extensive but not complete list is available from the CBOR website.

The given rate limits can be found from HTTP response headers, which giving information about the remaining quota and time in the current time window.

API endpoints which can be accessed in an unauthenticated state respond with the unauthenticated quote, while endpoints with authentication need respond with the corresponding authenticated quota though.

Requests that exceed the given quota return with the HTTP status 429 (Too Many Requests) and also provide a Retry-After header, which represents the number of seconds (in UTC epoch) to wait before retrying the request.

Additional headers represent values according to the following table:

The Service Id is a short alpha-numerical code, which is used in certain support requests and special operations, e.g. the AuthCode is not readable anymore.

The main reason behind the code is, it can be manually input (in contrast to the long AuthCode) and has a check digit at the end to catch basic input errors.

The first 8 characters are random printable ascii characters, while the last digit is the check digit. It is calculated according to the following pseudo code:

checkDigit := 0
for character in serviceId[0:8]
    checkDigit := checkDigit + ascii(character)
checkDigit := checkDigit % 10
checkDigit := 10 - checkDigit

ok := checkDigit == int(serviceId[9])

The unit of a ValueType is defined as in the following table.

This list only contains the most commonly used Value Types. In case a full list of Value Types is required, the Metadata API provides a call which retrieves all Value Type information.