Authentication¶

Almost all communication with the API requires prior authentication. Authentication happens through the exchange of data, signed with a private key. The API, which has access to the public key, verifies the validity of this signed data, and returns an authentication token. This token then needs to be passed in the request headers for each request.

Getting a private key¶

You must register with educa.ch to become a content partner. You will receive a private RSA key, a username (usually an email address) along with a passphrase. These three elements will be used by the client library to request an authentication token from the API.

Authenticating¶

Authentication is pretty simple:

use Educa\DSB\Client\ApiClient\ClientV2;
use Educa\DSB\Client\ApiClient\ClientAuthenticationException;

$client = new ClientV2('https://dsb-api.educa.ch/v2', 'user@site.com', '/path/to/privatekey.pem', 'passphrase');

try {
    $client->authenticate();
} catch(ClientAuthenticationException $e) {
    // The authentication failed.
}

The Client class will throw an exception in several cases:

The private key could not be read: check the path, or that the private key is readable.
The passphrase could not be loaded into memory: make sure the passphrase is correct.
The request failed: the server did not return a 200 status code. Check the error message.
The request succeeded, but the response did not contain a token.

If no exception is thrown, the authentication was successful. Once authenticated, the class can communicate with the API.

Chaining methods¶

The client class supports chaining methods. It is thus possible to chain an authentication with another action. For example:

use Educa\DSB\Client\ApiClient\ClientV2;
use Educa\DSB\Client\ApiClient\ClientAuthenticationException;
use Educa\DSB\Client\ApiClient\ClientRequestException;

$client = new ClientV2('https://dsb-api.educa.ch/v2', 'user@site.com', '/path/to/privatekey.pem', 'passphrase');

try {
    $client->authenticate()->search('Dog');
} catch(ClientAuthenticationException $e) {
    // The authentication failed.
} catch(ClientRequestException $e) {
    // The request failed.
}