Introduction

1.1 Authorisation

All API methods require authorisation via Ceffu API key. The API Key pairs can be created in the Ceffu WEB platform at Entity Management > API Management. As a result, API key and API key secret will be generated for authentication: API key and API key secret.

API Management module can only be accessed by: Creator role and Admin role only.

A Postman collection of apis is available on github. You can try excuting the apis by importing the collection files and filling in the variables.

1.2 Signing a Request

All request require signature of the request content. The signature should be signed with the Ceffu API secret key and the “SHA512withRSA“ algorithm. The request content require following format:

GET request: Query string in URL
POST request: JSON string in https request body

There is no restriction on the sequence of the parameters, but require the data to sign must be equal to the actual data in the request. The signature require to attach to the http header.

signature:${signature}

Python:

from Crypto.PublicKey import RSA
import base64
from Crypto.Signature import pkcs1_15
from Crypto.Hash import SHA512

# signature
def sign(data, secret):
    encoded_data = data.encode("utf-8")
    decoded_private_key = base64.b64decode(secret)
    private = RSA.import_key(decoded_private_key)
    hashed = SHA512.new(encoded_data)
    signed = pkcs1_15.new(private).sign(hashed)
    return base64.b64encode(signed).decode()

Java:

public static String sign(String data, String secret) throws Exception {
    KeyFactory keyFactory = KeyFactory.getInstance("RSA");
    byte[] decodedKey = Base64.getDecoder().decode(secret.getBytes());
    PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(decodedKey);
    PrivateKey key = keyFactory.generatePrivate(keySpec);
    Signature signature = Signature.getInstance("SHA512withRSA");
    signature.initSign(key);
    signature.update(data.getBytes());
    return new String(Base64.getEncoder().encode(signature.sign()));
}

Node.js :

const crypto = require('crypto')

const sign = (data, secret) => {
  const privateKey = crypto.createPrivateKey({
    key: Buffer.from(secret, 'base64'),
    type: 'pkcs8',
    format: 'der',
  })
  const sign = crypto.createSign('sha512WithRSAEncryption')
  sign.write(data)
  sign.end()
  const signature = sign.sign(privateKey, 'base64')
  return signature
}

Pseudocode:

rsa_sign(sha512(data), private_key)

1.3 LIMITS

Limits Introduction

The /open-api/* endpoints adopt access limiting rules - IP limits .

Each endpoint with IP limits has an independent 1200 per minute limit.

IP Limits

When a 429 is received, it's your obligation as an API to back off and not spam the API.

**Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban.

The limits on the API are based on the IPs, not the API keys.**

General Info on Limits

A 429 will be returned when either rate limit is violated.