Akkroo
  1. Support
  2. Developers
  3. API
  4. Authentication Methods

Authentication

The API endpoints require an access token in the Authorization header of every request. You can generate this token using a ‘Client Credentials’ grant http://tools.ietf.org/html/rfc6749#section-4.4. This is a simple process - you use the Client Credentials found in your account dashboard, then you perform a POST to the authorization endpoint, which will return your access token on success.

You can find your Client Credentials in Settings > API.

Once you have received your access token, store it in your application until it expires. You will use it in every subsequent API request.

Request

POST https://akkroo.com/api/auth
POST /api/auth HTTP/1.1
Authorization: Basic <client credentials>
Accept: application/vnd.akkroo-v1.1.5+json
Content-Type: application/vnd.akkroo-v1.1.5+json

{
    "grant_type": "client_credentials",
    "username":   "<company username>",
    "scope":      "PublicAPI"
}

The body content is in JSON format, and POSTed to the endpoint with the client credentials in the headers.

Parameters

grant_type
"grant_type": "client_credentials"
Should always be defined as "client_credentials"
username
"username": "example"
Only required if you are integrating with more than one user account. You can find your Company Username in Settings > Account.
scope
"scope": "PublicAPI"
Should always be defined as "PublicAPI"

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.akkroo-v1.1.5+json

{
    "access_token": "hS4sfKsdlPPg74tbg7u0ghjPW1EBWrej0g9111SR2KHGsAxXNSs32",
    "expires_in":   "86400",
    "token_type":   "bearer",
    "scope":        "PublicAPI"
}

The server returned an access token which can be used to perform further API requests.

You need to store both the access_token and the expires_in for future calls to the API (otherwise you’ll have to request them again, which will slow things down).

The expires_in parameter lets you know when the access_token expires. When your access token has expired you will need to regenerate a new access token and update the details in your database. We recommended that you check if your token is still valid before performing any API request, this will ensure you do not waste time performing a request that will fail.

Parameters

access_token
"access_token": "hS4sfKsdlPPg74tbg7u0ghjPW1EBWrej0g9111SR2KHGsAxXNSs32"
String field
expires_in
"expires_in": "86400"
Seconds
token_type
"token_type": "bearer"
String field
scope
"scope": "PublicAPI"
String field

Using the access token

Once you have received the access token, use it to authorise every API request. For example, when performing a GET request on the Company endpoint:

    GET https://akkroo.com/api/company
    GET /api/company HTTP/1.1
Authorization: Bearer <access_token>
Accept: application/vnd.akkroo-v1.1.5+json
Content-Type: application/vnd.akkroo-v1.1.5+json

HTTP/1.1 200 OK
Content-Type: application/vnd.akkroo-v1.1.5+json
{
	"id":2,
	"lastModified":"Thu, 01 Aug 2013 10:01:27 +0100",
	"name":"Example Company",
	"urlHash":"abcdefghijkl",
	"username":"example",
	"appPasscode":"12345"
}