Call us: +1 (716) 989 6531 or email at:

search
login/signup

Forecasting Software for retail, wholesale and manufacturing

RSS RSS

Navigation





Search the wiki
»

PoweredBy

Lokad.TinyAuth, a tiny REST API to obtain API keys

RSS
Developers » Here

Lokad.TinyAuth, a tiny REST API to obtain API keys

Lokad is designed to be integrated into 3rd party apps - called client apps. If the client app happens to be a web app, then Lokad.TinyAuth is tiny REST API that provides a user friendly way to setup Lokad instead of having to rely on the user to perform a manual setup.

Lokad.TinyAuth includes two commands:
  • create a new Lokad account on behalf of the client.
  • acquire API keys from an existing Lokad account.

This framework is nothing but a drastically oversimplified variant of the OAuth protocol. It's nowhere near as powerful and expressive, but it requires about 15min of coding to be implemented.


1. Opening a new Lokad account

Lokad's partners can open account on behalf of their own users. Opening a partner account is free. Sign-up now for a partner account.

If you wish to power your app with the Lokad forecasting technology, you can ease the setup of your users by auto-opening Lokad accounts on their behalf.

Creating a new Lokad account is accomplished with a single GET web request:

http://app.lokad.com/rest/newaccount.ashx?partnerkey={key}&email={email}&name={name}

Caveat 1: it's app.lokad.com not api.lokad.com

Caveat 2: parameters need to URL Encoded.

Upon reception of this request, Lokad generates new account. If the call is a success (HTTP.OK 200), then an API key is returned immediately in the response. The body of the HTTP response looks like:

HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Content-Length: 40

MiyxTAEDiKtaAnaOntl4JgQ9o9ZHQd//IbSqmY8=

1.1 Parameters

partnerkey
Partner key is an API key associated with your partner account. From your partner account, you can obtain a new API keys from the User management section.

Image


An API key is just an alternative to the Login/Password pair that simplifies the call authentication. Partner can have any number of API keys associated with their account.

Image


API keys, just like any other value, MUST be URL-encoded, when passed as an URL parameter.

email
The email of the client must be passed to the system. Duplicate emails are not allowed, and an error will be returned if another email is detected. This email will be used by Lokad to send to the client its login credentials. Then, later on, the client will need a direct access to her Lokad account for billing purposes.

name
The name is an optional (but recommended) parameter used as the human-readable name for the client. If it is absent, email is used as the name. The client can change this value later on from the dashboard of her own Lokad account.

1.2 Errors

Malformed request
If either of two required parameters are missing, response redirects to the original documentation.

HTTP/1.1 302 Found Location: http://www.lokad.com/tinyauth-guide.ashx#New_Account Content-Type: text/plain; charset=utf-8 Content-Length: 169 Connection: Close

Authentication failure
If authentication fails for some reason, then HTTP Forbidden (403) error code is returned with the error description in the response body.

HTTP/1.1 403 Forbidden Content-Type: text/plain; charset=utf-8 Content-Length: 80 Connection: Close

Provided key is in invalid format. Please contact your administrator or support.

Possible failure reasons include, but are not limited to:

  • Invalid key format
  • Unknown key
  • Expired or locked key

Validation Failure
If the request could not be carried out for some reason, then this is indicated by HTTP Bad Request (400) error code. Error description is included in the response body.

HTTP/1.1 400 Bad Request Content-Type: text/plain; charset=utf-8 Content-Length: 22 Connection: Close

Error. Duplicate email

Possible failure reasons include, but are not limited to:

  • Duplicate email
  • Account requesting operation is not a partner

1.3 Remarks

Delayed activation It might take up to 15 minutes for the account to be activated in the system. Before this happens, the API key will not work for logging into the new account.

Automatic affiliation New accounts are automatically associated with the partner, so there is no need to call SetPartner method of Forecasting API.

Account notification Owner of the email will receive notification message, with the information about his new account. This message will receive credentials for logging into the dashboard.

2. Acquire an API key from an existing Lokad account

Image


The workflow follows a two stage process, relying only a single GET arguments being passed between the client app and Lokad.

2.1 Forward from client app toward Lokad

The client app redirect the user toward the URL:

http://app.lokad.com/account/getkey.aspx?returntourl={0}

The GET argument {0} represent an URL-encoded string that precisely represents the URL where the client should be redirected to once the access has been granted.

2.2 Lokad forwards back to client app

Once the user has granted access on his Lokad account, the Lokad appends the API Key as a GET argument and forwards the user toward the URL:

http://www.return-url.com?foo=bar&lokadkey={0}

The return URL may, or may not, already have GET arguments other than lokadkey, Lokad takes care of correctly formatting the return URL while appending the extra GET argument.

2.3 Understanding the integration workflow

Our Forecasting API provides two distinct authentication methods: username/password and API keys (the later being the favored approach, both more secure and more reliable).

The naive workflow to enable Lokad into a client web app goes as follow:
  1. The user is redirected from the client app toward Lokad.
  2. The user registers on Lokad.
  3. The user generates an API key from the Lokad account.
  4. The user navigates back to the originating client app.
  5. The user pastes the API key into the client app.
  6. The client app is now ready to access Lokad.

The process is a bit tedious, Lokad.TinyAuth automates steps 3, 4 and 5:
  • The user is auto-redirected to the originating client app.
  • The API key is auto-generated.
  • API key is carried back to the client app during the auto-redirect.

Products developed by Lokad as open source are released under the BSD license. The BSD license is compatible with both open and closed-source applications. Integrating a forecasting technology has never been easier.

Our projects are now primarily hosted on GitHub, but older projects can still be found on Google Code.

What people say

From a developer standpoint, we found that the Lokad API was very well documented and easy to use. The Lokad team was also extremely responsive to any questions we had. Most importantly, we were able to develop a Lokad plugin for our data browser in very short order. Jeff Engel, Kirix Corporation

Open-source strategy

Our intellectual property (IP) strategy is simple: we release as open source blocks that have a lot of potential for reuse while we keep private the very core of our technology. By doing so, we benefit from community feedback and exposure. It drives us to produce leaner and more reliable blocks that we leverage to deliver better services. IP loss is minimal because reuseable blocks are bound to be redeveloped by dozens of companies anyway, and are merely increasing the entry barrier for our competitors by a few inches at best. Instead, by making those blocks accessible, it gives us an edge to focus on the core: parts both extremely specific to our business and truly hard to reproduce. Joannes Vermorel, Lokad, Founder