Authentication

Documentation

The OAuth specification documentation can be found here. The grant flow we have implemented, is the OAuth 2.0 Client Credentials Grant, documented in section 4.4.

Third party OAuth libraries can be found at oauth.net . If you use a third party oAuth library to assist with the authentication process, the application key is provided as the client key value, and the client key must be provided as the client secret.

Prerequisites

Before your integration component can be authorized to perform API calls, you must first register as a developer to obtain an application key. Read the getting started section for the required steps.

In our demo environment, we provide a test client in Go with the application key already activated, thus providing you the client key as well when you get started with testing. We also send user invites to the test client, providing GUI access for you to the test environment. Should you choose to add more test clients, you will need to activate your application key on the new clients using either the GUI or the onboarding endpoint, as we have described here.

In production, we only provide the application key, and thus the ability to access the production environment, if and when customers choose to activate your integration on their Go clients. When doing so, each Go client and instance of the integration, will have its own unique client key.

URLs

It is important to notice that there are different URLs for the demo and production environment, and that it is not possible to mix access tokens between the two environments. Subscription-, Application- and Client-Key all need to be from the same environment when requesting access token.

To obtain an access token you must use the "Token" endpoint in our "Authentication" API. Documentation for the API and endpoint can be found under APIs.

For the demo-environment the URL to request access token is:
https://goapi.poweroffice.net/Demo/OAuth/Token

For the production-environment the URL to request access token is:
https://goapi.poweroffice.net/OAuth/Token

Our main API - "API v2" requires a valid access token on all endpoints. If the token is not valid, a "401 - Unauthorized" error will be given.

For the demo-environment the base URL for all api-calls is:
https://goapi.poweroffice.net/Demo/v2

For the production-environment the base URL for all api-calls is:
https://goapi.poweroffice.net/v2

Definitions

• Application key (Applikasjonsn?kkel):
  A unique, but fixed key assosiated with your integration (the Integrated Application). Unique per environment, meaning the demo and production application keys are separate.

• Client key (Klientn?kkel):
  A key unique for each client integration instance (instance of the application key activated on a given Go client). Must be treated and stored as a secret. As only one instance of an application key can be activated on a given Go client, we commonly refer to the client key being unique per client.

• Product subscription key:
  A unique key representing the product subscription the integration use in the PowerOffice developer portal. Also uniqe per environment, the subscription keys for demo and production are separate. The user with access to our developer portal will find the subscripion keys when login in to the portal.

• Access token:
  A unique token granted after authenticating with the application key, client key and subscription key. The access token is thus unique per client integration instance and environment, and should be stored and treated as a secret. Expires after 20 minutes.

The authentication and authorization process

Before any API calls can be made to a server environment, you must first authenticate and authorize with the authorization server and get an access token (for each client integration instance). The access token is valid for 20 minutes, and must be used in each api call, along with the subscription key.

Requests to the authorization server must provide the application key and client key in the Authorization header. The keys must be separated by :, and the whole string must be Base64 encoded.

The header Ocp-Apim-Subscription-Key must also be included (in all type of requests), and set to the product subscription key you have.

The Content-Type header must be set to application/x-www-form-urlencoded and the body must contain grant_type=client_credentials

A typical request for access token will look something like this:

POST https://goapi.poweroffice.net/OAuth/Token 

Head:

Authorization: Basic MTk3MEY2QUQtRTM1RS00RUJGLTlEQTctNTEwOTYyQ0U3RTQ2OjE4MTM1NDRCLUNGMDgtNDlFNy1BOTYwLTBENDM0NEFCRTJDMQ== 
Ocp-Apim-Subscription-Key: 5Aad5baabc59458184773ab1539810ed 
Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials

The response from the authorization server would then look something like this:

Head:

STATUS: 200 OK 
Content-Type: application/json; charset=utf-8

Body:

{ 
"access_token": "eyJSM8aIY5SQofcuLZnOkTvuTL5N-RLepbX2xdUIE39zW-JhCQDyqAnXjUMW1nbfA2u3My4iWny5pA1u_wceV64WWPj9UUo927cp5AKojxbkH8Wbjnie2656VXzZ6nnftYl55j3Dz-5t_a8YPHgaPGkMXJ6tus2sagtsrb6MiPoxD36dGyPiefmLVthO9DfvM2UmDGXCwjV9yPI5g4QNEqvOmLwGAWnjo8s0oVsT7IMhsBZQe4rFIUNRkuF1-qwySMy_eMpbfoXKaiTYMowDb8f8pxMuWGn7HOLS2vEXq72m-Bl95hKNcGRbFcww1WFGDy7_0q3QaIxHxz4sImFZf5xaD0cxDt2YFMlaD9UjheR6OfKjcYbhg7PK_wNh-VNzTNJKMUu8zdRTiO28QBxLq91TQHnRaS4_V-FYhxOiR3LyGFDzBXzBZyUfVd5_GxjT4H8JdPGoqz85ffZRm2YetBCnPP_ue5XPvSoHhKX_ANsxH8Tf7bn4QVChiR3oS4KTTs", 
"token_type": "bearer", 
"expires_in": 1200 
}

The access token and time of expire should be safely stored somewhere to be reused on subsequent api request. We reiterate that the access token is valid for a singular client integration instance (a single client). The access token can be reused by new sessions communicating with the given client, until it expires. A new access token must then be requested.

Calling an API

After obtaining an access token for a client in an environment, api functions can be called using the access token and the subscription key and the url's that correspond with the environment in question. They are used to both authenticate and authorize the api call. A typical request will look something like this:

GET https://goapi.poweroffice.net/v2/customers/ HTTP/1.1 Authorization: Bearer eyJSM8aIY5SQofcuLZnOkTvuTL5N-RLepbX2xdUIE39zW-JhCQDyqAnXjUMW1nbfA2u3My4iWny5pA1u_wceV64WWPj9UUo927cp5AKojxbkH8Wbjnie2656VXzZ6nnftYl55j3Dz-5t_a8YPHgaPGkMXJ6tus2sagtsrb6MiPoxD36dGyPiefmLVthO9DfvM2UmDGXCwjV9yPI5g4QNEqvOmLwGAWnjo8s0oVsT7IMhsBZQe4rFIUNRkuF1-qwySMy_eMpbfoXKaiTYMowDb8f8pxMuWGn7HOLS2vEXq72m-Bl95hKNcGRbFcww1WFGDy7_0q3QaIxHxz4sImFZf5xaD0cxDt2YFMlaD9UjheR6OfKjcYbhg7PK_wNh-VNzTNJKMUu8zdRTiO28QBxLq91TQHnRaS4_V-FYhxOiR3LyGFDzBXzBZyUfVd5_GxjT4H8JdPGoqz85ffZRm2YetBCnPP_ue5XPvSoHhKX_ANsxH8Tf7bn4QVChiR3oS4KTTs Ocp-Apim-Subscription-Key: 5Aad5baabc59458184773ab1539810ed

Authorised access privileges

In our demo environment, you will have general access to all v2 endpoints included in the common workflows, in order for you to properly test and explore the api.

When you are provided with an application key for production, appropriate v2 api privileges will be set for the application, according to what is needed for your particular workflow and what we have agreed upon. The privileges apply at the application key level, and as such on all client integration instances of that application key. However, the privileges require that the clients have the appropriate Go subscriptions (in most cases the client needs only an active subscription in general, not requiring a particular Go module).

An example might be that an application has the access privilege for retrieving time tracking entries from Go, but a given client might not have an active subscription of the time tracking module in Go. Api calls trying to retrieve timetracking entries from that client will be unauthorised to do so.

The general privileges and the specific client privileges, are set as part of the access token retrieved. The endpoint ClientIntegrationInformation can be used to retrieve a specification of the privileges granted for a particular access token (i.e. a particular client). The specification will list the clients subscriptions, the valid privileges on the access token, and any invalid privileges caused by missing Go subscription.

Storing client keys and access tokens

The client key represents a unique instance of the integration on a unique client in Go, per environment. As only one instance of an application key can be activated on a given Go client, we commonly refer to the client key being unique per client. Note that if the client deletes the integration in Go, and reactivates it, a new instance and client key will be generated.

As the client key uniquely identifies the client, this applies for any given access token as well - the token is unique for a given client in its 20 minute lifetime. The client key is a secret that should be stored as such. Avoid exposing the client key in places where other parties can see it - it should preferably be stored in a secure place, and encoded in a non-human readable form. In our end, when a client activates a given integration on their Go client, and thus creates a new client key, we only present the key in the first-time dialogue. After activation, the key is salted and hashed, and cannot be retrieved again by us if lost.

We recommend storing access tokens in a secure repository, and we highly recommend that you be aware of the technological components you use in multithreaded processes. This is especially important if your integration is to be used by many different clients (and as such will be handling many different client keys and different access tokens). We have seen examples of certain technical components that are default set to share repositories in multithreaded processes, providing a risk of data leakage between Go clients if not handled correctly (reprogramming of the component). The process you create must be thread safe when the integration is to communicate with multiple Go clients.

It is your responsibility to ensure the correct and secure handling of credentials and access tokens, regardless of the setup of your external system and the technology used. Getting this wrong and mixing access tokens, thus retrieving from or sending data to the wrong clients, may have severe consequences for the clients, so this is a point we need to stress in terms of awareness.