Authentication & Authorization

Every request sent must include an Authentication header. Onslip 360 uses Hawk for authentication, which can be seen as a derivate of OAuth 1.0 (but a different derivate than OAuth 2.0). Its main advantage is that it's fully stateless and the secret is never transmitted over the network, not even in encrypted form.

info

Even though we do not use OAuth 2.0 Bearer tokens, you can still use the OAuth 2.0 Authorization Code Flow to generate API access tokens for your users.

Hawk

There are plenty of Hawk libraries to select from for various programming languages. For example:

• Hawk itself is a JavaScript implementation of the protocol.
• dflydev-hawk is a PHP implementation.
• .Net, Java, Ruby, Python and Go implementations are linked from the Implementations section on the Hawk API documentation.

tip

If you use one of the SDKs we provide, the Hawk authentication is automatically handled for you by the SDK and not really something you have to think about.

Key Types

Instead of username & password, Hawk uses the terms key identifier, key and algorithm. The algorithm used by Onslip 360 is always SHA-256.

This section may be a bit complicated, so there is a short version and there is a long version.

Short version: When creating an API access token on the Onslip 360 Backoffice site, you will be given both the key identifier and the Base 64-encoded key. Simply feed those credentials into your Hawk library and you're ready to go. Please note that you may have to decode the key before using it, depending on your Hawk library.

For integrations that will be available to all Onslip 360 users, you should use the platforms support for the OAuth 2.0 Authorization Code Flow to generate the API access tokens, instead of asking them to generate tokens manually.

Long version: In Onslip 360, key identifier is an URI-like string, similar to mailto: URIs, that is used to identify the client and the method of authentication.

Key identifier	Key	Description
dev:{device}@{realm}	A 256-bit random key	Identifies a trusted device.
key:{user}+{token}@{realm}	Generated by the server	An API access token, managed from Backoffice.
pin:{user}@{realm}	Derived from the PIN	A user, authenticated by a 4-digit PIN code.
pwd:{user}@{realm}	Derived from the password	A user, authenticated by a password.

{realm} in the table above refers to the company alias.

The key:{user}+{token}@{realm} key identifier in the table above is the "short version" mentioned earlier. This is the authentication method you must use when integrating with Onslip 360.

The key derivation algorithm used for PIN and passwords—UTF-8-encoded, of course—is:

key = PBKDF2(HmacSHA256, HmacSHA256("{password/pin}", "{type}:{user}@{realm}"), "{type}:{user}@{realm}", 16384, 32);

where {type} is either pwd or pin.

Key identifiers may be combined by sending multiple space-separated identifiers. For instance, the following string identifies user mb at company alias onslip.com, authenticated using a PIN code on the trusted device A.da14b0389d7371e7 (bound to the account onslip.com).

pwd:mb@onslip.com dev:A.da14b0389d7371e7@onslip.com

The actual keys should be combined by feeding the individual keys to the HmacSHA256 algorithm:

key = HmacSHA256(key1, key2);

Permissions

Every trusted device, user or API access token comes with a set of permissions that defines what the client is allowed to do. For most resources, there is one permission for reading from it and one for writing to it, but some resources use additional permissions.

The permissions are documented together with the resource to which they belong.

Permissions may be acquired in a couple of different ways:

• Some authentication methods implicitly grant permissions. For instance, a trusted device will automatically be given the show-tills, show-users and add-certs permissions.
• A user obtains permissions either via the pre-defined system roles or the custom Role entities.
• An API access token, in contrast, is always associated with a user and instead reduces the user's permissions.

note

If an access token belongs to a user with the service system role (which has no automatic permissions), the permissions are taken directly from the access token instead.

Not all permissions are available for all authentication methods. For instance, while edit-customer is available via both pin-based user authentication from a trusted device and via password-based authentication, edit-users always requires password-based user authentication, even when performed from a trusted device.

In general, almost all permissions are available via password-based user authentication or via API access tokens, while most are also available via pin-based user authentication from a trusted device.

The actual set of permissions is returned as part of the getClientInfo response.