Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



37 Commits

Repository files navigation

One Community

An easy-to-use PHP client to access the One Community API.


Using Composer:

composer require onecommunity/client

Contact us with your public key to receive your API key.


Initializing the Client

use OneCommunity\Client;

$apiKey = "xxxxxxx";
$projectName = "yourproject";
$userId = 1;

$client = new Client($apiKey, $userId, $projectName);

// Load private key from file..
// ..or string

Sending Requests

See the Examples directory for working examples.


Returns the User object of the authenticated user. Great for testing.

use OneCommunity\Requests\UserRequest;

$request = new UserRequest;
$response = $client->send($request);

if ($response->isSuccessful()) {


use OneCommunity\Requests\SendTransactionalMailRequest;

$accountId = 1; // Recipient
$transactionalMailId = 1; // Mail

$request = new SendTransactionalMailRequest($accountId, $transactionalMailId);
$request->setSubstitutions(['gift' => 'Free coffee ☕']);

$response = $client->send($request);


The following HTTP status codes are used:

HTTP Status Code Description
200 OK Everything is OK, the body contains the payload.
400 Bad Request Indicates an authentication error.
404 Not Found Some ID refers to an unknown model (e.g., unknown account or mail).
422 Unprocessable Entity Validation errors.
429 Too Many Requests You cannot send more than 60 requests per minute.

If anything unexpected occurs a OneCommunity\Exceptions\RequestException is thrown (e.g., if the API does not return a valid JSON response).

All responses (except 200 OK) contain a message attribute, explaining what went wrong. Furthermore, 400 Bad Requests responses contain a code attribute which can contain one of the following values:

code message
100 Invalid API key
101 Could not decode Bearer token
102 No API key found on request
103 No Bearer token found on request
104 Token could not be verified
201 Client not found
202 User not found or not accessible by this API Client
501 No access to this project or invalid project
502 No access from this IP

The validation errors of a 422 Unprocessable Entity response are structured as follows:

    "errors": {
        "field1": [
        "field2": [


The API is based on JWT API, an efficient and secure machine-to-machine API using JSON Web Tokens and asymmetric request signing. Advantages of this approach include:

  • Requests and responses are sent over a secure channel.
  • Requests can only be signed by the API consumer (providing non-repudiation).
  • Requests are only valid for a short time (avoiding replay attacks).

Due to the asymmetric nature of this protocol, a public/private key pair needs to be generated (RSA 2048 bit). The key pair can be generated by issuing the following commands. Please send your public key (public_rsa.pem) to us and keep your private key safe.

Generating the Public/Private Key Pair

# Generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

# Generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem