Authentication

Since Staction is a closed system where each account has access to an entirely different view of the database, every call you make to the API needs to have authentication information.

HTTP Method

POST

Required Parameters

  • developerKey: more on this below.
  • account: the name of the account registered in Staction. This is the subdomain of the full URL that’s used to access the account through the regular website. For example, if the URL is http://mycompany.staction.com, this API field should be “mycompany”.
  • email: the email address of the registered user.
  • password: the password of the registered user.

What’s the developer key?

The developer key is an unique string that each developer needs to request through this page in order to have access to the API. The main goal of this is to let us see what each application being developed on top of the API is doing, and how it’s handling the Staction information. In addition to visibility, it also allows us to more effectively tweak our database to provide faster results to the API users.

Please note that this key is only supposed to be used when creating an application and not per user accessing your application. Let’s take a look at a simple example to make things clearer:

  1. John is a developer that wants to do a desktop application using the Staction API so he needs to request a key through our page, mentioned above.
  2. He will use this key to gain access to the API, and it can be a constant inside his code since it will never change.
  3. Inside his application, he will need to ask for account name, email address and password for his users.

Examples (using curl)

  • curl -d “developerKey=123&account=paste&email=test@pasteinteractive.com&password=mypassword” http://api.staction.com/entries/list.json

Testing credentials

You can test authentication credentials by making a call to the account/authenticate URL as exemplified below. This call, if successful will return the user information of the person you’re authenticating.

  • curl -d “developerKey=123&account=paste&email=test@pasteinteractive.com&password=mypassword” http://api.staction.com/account/authenticate.json

Expected responses

If the call is not executed properly, the API will return an error in the default error format with a status field set to false, and a reason field explaining why it failed to run (respecting the format requested). If the call runs properly, it will return all your entries respecting the format you requested.

As an example, here’s a parsed JSON response, transferred into a multidimensional array for the sake of clarity.

Array
(
    [id] => 1
    [is_account_holder] => true
    [name] => Brian
    [email] => brian@pasteinteractive.com
    [week_begins_on] => Sunday
    [timezone] => America/Sao_Paulo
    [created_on] => Sat, 15 Mar 2008 01:55:41 +0000
    [last_updated] => Mon, 20 Jul 2009 20:52:30 +0000
    [last_accessed] => Fri, 28 Aug 2009 18:55:09 +0000
    [is_https_on] => true
)

Dealing with HTTPS

It’s up to the developer to figure out if the application needs to make HTTPS or regular HTTP calls to the API, depending on the settings from the logged account (i.e.: SSL encryption turned on/off through the Staction preferences page of the account holder). Using the account/authenticate call described above (which ignores HTTPS/HTTP restrictions), you can use the is_https_on value to find out which protocol to use.

Please note that if the account has HTTPS switched on and your application makes an API call through HTTP, you will get an error message. The opposite is also true, and the only exception to this rule is on the account/authenticate call which runs independently of the protocol used.