Authentication

This article describes how to authenticate against the Laboperator API using OAuth 2.0.

If you are not familiar with OAuth, yet, you can get started with some useful resources to understand the basics. Here we will only cover the basic authentication with some examples in curl to get started.

1. Prerequisites
2. Password Grant Flow
3. Authorization Code Grant Flow
4. Using Refresh Tokens
5. Token Expiration

Prerequisites

Every third-party code that wants to authenticate against the API needs to be registered as an OAuth Client or in the Laboperator domain an Application. 

Read more about how to create an Application from your Laboperator admin account.

Password Grant Flow

Using the password grant flow is the simplest flow, but also the least secure and not recommended except for test purposes. 

In this flow, a token is requested in exchange for the resource owner credentials (username and password).

To request an Access Token using the Password Grant flow you need to send a POST request to <HOST>/oauth/token with the following parameters (replacing your credentials and client id/secret):

{
  "grant_type": "password",
  "scope": "read write", // space delimited
  "username": "user@company.com",
  "password": "password",
  "client_id": "3eadf0ec9cb113ac1501aba8eef1f67a4e537a0b6cf650bb8e61869f1572dbe3",
  "client_secret": "357dd3d72a386510745c6dc42ebfd7e2862ed4184c4f632bd9a33eaaaa0d9d2c"
}

As a curl request you can execute from the terminal this would be:

curl -X POST 'https://company.cubuslab.com/oauth/token' \
     -H 'accept: application/json, text/plain, */*' \
     -H 'content-type: application/json; charset=utf-8' \
     -d @- << EOF
       {
         "grant_type": "password",
         "scope": "read write",
         "username": "user@company.com",
         "password": "password",
         "client_id": "3eadf0ec9cb113ac1501aba8eef1f67a4e537a0b6cf650bb8e61869f1572dbe3",
         "client_secret": "357dd3d72a386510745c6dc42ebfd7e2862ed4184c4f632bd9a33eaaaa0d9d2c"
       }
EOF

The body of resulting response should look somewhat like this:

{
  "access_token": "95c94b095acd6cee1a9d57e84e4accc7a57731f15617989c1854986a01a245d7",
  "refresh_token": "ceab980ae839a5508acb5c36158c02759d8cff8eea6fd04ceab70c81c11e8de4",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope":"read write",
  "created_at": 1497445122
}

You can now use this access token to make authenticated API requests by including the Access Token in the authorization header of your request:

curl -X GET 'http://company.cubuslab.com/api/v1/devices' \
     -H 'accept: application/json' \
     -H 'authorization: bearer 95c94b095acd6cee1a9d57e84e4accc7a57731f15617989c1854986a01a245d7'

Authorization Code Grant Flow

Documentation coming soon.

Using Refresh Tokens

With an Access Token you will also get a Refresh Token that is only valid once. It can be used to get a new Access Token. This is useful once the current Access Token has expired (see Token Expiration below).

To request an new Access Token using the Refresh Token you need to send a POST request to <HOST>/oauth/token with the following parameters:

{
  "grant_type": "refresh_token",
  "refresh_token": "ceab980ae839a5508acb5c36158c02759d8cff8eea6fd04ceab70c81c11e8de4"
}

As a curl request you can execute from the terminal this would be:

curl -X POST 'https://company.cubuslab.com/oauth/token' \
     -H 'accept: application/json, text/plain, */*' \
     -H 'content-type: application/json; charset=utf-8' \
     -d @- << EOF
       {
         "grant_type": "refresh_token",
         "refresh_token": "ceab980ae839a5508acb5c36158c02759d8cff8eea6fd04ceab70c81c11e8de4"
       }
EOF

The body of resulting response should look somewhat like this:

{
  "access_token": "4a9ddfefae6c7c21d230785c6ac2f60e6314a8f6150475c84bf4abd964a3ee89",
  "refresh_token": "e7d2c22f1195bd12753c296e7959e6291f818abef782b58521e717348e12a639",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope":"read write",
  "created_at": 1569948219
}

You now have a fresh Access Token and a Refresh token so you can potentially keep repeating this scheme so user won't have to authorize your application again. The user can however revoke the access at any time.

Token Expiration