API Authentication

This describes how to get access to the Apis as well as how authentication works.

Grant Victor offers applications the ability to issue authenticated requests on behalf of an application.

This differs from authentication on behalf of a specific user.

The foundation of this implementation is:

• Client Credentials Grant
• OAuth 2 Specification

The Flow

The application-only auth flow follows these steps:

• An application constructs its credentials from the consumer key and secret.
• An application makes a request to the POST oauth2/token endpoint to exchange these credentials for a bearer token.
• When accessing the REST API, the application uses the bearer token to authenticate.

With BASIC auth using the consumer credentials

'Authorization':'basic mycred123', 'Content-Type':'application/json'

POST oauth2/token -----> {"tokenType":"bearer","accessToken":"my_token"}

POST oauth2/invalidate_token {"accessToken":"my_token"} -----> {"accessToken":"my_token"}

With BEARER auth using the bearer token

'Authorization':'bearer xyz'

GET  someresource/123 -----> {"id":123, "name":"George"}

About

• Protect the key, secret and bearer tokens as a passwords
• HTTPS (SSL) is required as these values will be in the headers
• This access is at the level of the calling application and does not lend itself to user based data and access.

How To

Convert the key and secret to a credential by format "key" + ":" + "secret"

Place in the header as basic auth:
'Authorization', 'basic my_key:my_secret'

Obtain a bearer token

Note: susequent calls to POST oauth2/token will create a new token and replace the old one.

Tokens expire within an hour.

POST https://api.grantvictor.com/oauth2/token HTTP/1.1
Authorization: basic my_key:my_secret
Content-Type: text/plain;charset=UTF-8

on 200 Ok

{
  "tokenType" : "bearer",
  "accessToken" : "my_token"
}

Authenticate API requests with a bearer token e.g. GET /apps/{appId}

GET /apps/636 HTTP/1.1
Authorization: bearer my_token
Accept: */*

on 200 Ok

{
"id" : 88,
"name" : "Pioneer Co",
"ts" : 1383861882787
}