Transition
from v1 to v2
Introduction
If have been using the v1 api, one of two situations apply:
You are live with a v1 applicationkey in our production environment, and you also have an applicationkey in our demo environment
You are not live in production, but have been testing with an applicationkey in our demo environment
In either case, we will start of by providing you v2 access for our demo environment with an applicatonkey you already have in this environment. You should take your time to explore and test the v2 api's in an isolated environment.
When you contact us, we will provide a form to you for updating our contact information. Specifically, we need to know who we should invite to the v2 developer portal (usually the lead developer of the integration). After the form is completed, we will send the invite to the developer portal, and upgrade your existing demo application key with v2 access privelliges.
In order to test the v2 api's, you can use your existing demo application key and the clientkey(s) you have for test clients in the environment. The v2 endpoint url's will be new, and all api calls made towards the v2 endpoints must include the product subscription key found in the developer portal.
Overview of keys, url's and where to find them
Since you will be handling multiple URLs and various keys and tokens, here is a concise overview to clarify what each element is and where to locate it. While more detailed technical definitions can be found elsewhere on this portal, this overview is designed to assist in practical sorting of concepts during a transitional phase.
About the environments
Demo and production are separated, the demo environment running the same version as production, but being isolated with many simulated GUI features for testing purposes (i.e. a sandbox environment).
The developer portal and documentation are shared, the https://developer.poweroffice.net/, but everything else (url's, keys) are separated for demo and production - as explained below.
The DEMO environment
Applicationkey: A fixed key that uniqely identifies your integration in the demo environment. You received this by e-mail the first time your company got access to our demo environment. If lost, contact us. This key is default private in the demo environment, meaning that clients won't see your integration listed in Go, and when adding the the integration on a demo client this must be done by adding a "custom" integration using the applicationkey.
V1: The applicationkey have access priveliges set for the v1 api endpoints
V2: The applicationkey will get access priveliges set v2 endpoints when you get upgraded
Clientkey: For all practical purposes, this key is unique per client that have activated your integration. You received one such key by e-mail the first time we provided you access to a test client in our demo environment. If lost, you should log in to your testclient (GUI), delete and reactivate your integration to generate a new unique key for the client (or use onboarding to do so). For any other test clients you have access to or want to create in the environment, the process will be the same: Activate your integration (applicationkey) to generate and retreive the uniqe clientkey per client. Although the demo environment is a test environment, you should still treat the clientkeys as secrets and store them as such.
Access Token: You use the applicationkey and the clientkey in an auth process to retreive an access token. The token is unique for the given clientkey, thus unique for the client. V1 and v2 uses two separate access tokens, which is the reason you can use both v1 and v2 endpoints with your existing application key and clientkey(s).
V1: AccessToken lasts 10 min, and only work for v1 endpoints. Also have the concept of a refresh token
V2: AccessToken last 20 min, and only work for v2 endpoints. Refresh token is not used for the v2 platform, as we consider it redundant. To retreive the v2 access token, the subscription key must be included in the auth api call.
Subscription key: V2 only. A unique key for your subscription to the v2 api product package in the demo environment. Your lead developer can find this key by logging in to the developer portal. This key must be provided i all v2 api calls, including auth and onboarding calls.
Url's:
GUI: Logging in to the demo environment GUI: https://godemo.poweroffice.net/
Auth:
V1:
https://api-demo.poweroffice.net/oauth/token
V2:
https://goapi.poweroffice.net/Demo/OAuth/Token
Base endpoint url's:
V1:
https://api-demo.poweroffice.net/
V2:
https://goapi.poweroffice.net/demo/v2
The PRODUCTION environment
Applicationkey: A fixed key that uniqely identifies your integration in the production environment. You will receive this by e-mail the first time your company get access to our production environment. This key is either private or public in the production environment, depending on whether your integration is for internal use/is in a pilot phase, or if you need a public and marketed integration.
V1: The applicationkey may have access priveliges set for the v1 api endpoints you still need
V2: The applicationkey will get access priveliges set to the v2 endpoints you need
Clientkey: For all practical purposes, this key is unique per client that have activated your integration. Only users of a client (with access priveliges to do so) can activate integrations - i.e. the clientkey is something the clients provides to you if and when they choose to activate the integration. A client user either activate your integration manually and provide you with the clientkey, or they use the onboarding feature if you have implemented this.
Access Token: You use the applicationkey and the clientkey in an auth process to retreive an access token. The token is unique for the given clientkey, thus unique for the client. V1 and v2 uses two separate access tokens, which is the reason you can use both v1 and v2 endpoints with your existing application key and clientkey(s).
V1: AccessToken lasts 10 min, and only work for v1 endpoints. Also have the concept of a refresh token
V2: AccessToken last 20 min, and only work for v2 endpoints. Refresh token is not used for the v2 platform, as we consider it redundant. To retreive the v2 access token, the subscription key must be included in the auth api call.
Subscription key: V2 only. A unique key for your subscription to the v2 api product package in the production environment. Your lead developer can find this key by logging in to the developer portal. This key must be provided i all v2 api calls, including auth and onboarding calls.
Url's:
GUI: Logging in to the production environment GUI: https://go.poweroffice.net/
(rarerly relevant for an integrating party, unless the integration is for internal use)Auth:
V1:
https://api.poweroffice.net/oauth/token
V2:
https://goapi.poweroffice.net/oauth/token
Base endpoint url's:
V1:
https://api.poweroffice.net/
V2:
https://goapi.poweroffice.net/v2