Connection sur WAPI avec OAuth2.0
WAPI, acronym for WIT-DataCenter Plateform API, use the standard protocol OAuth 2.0. Our implementation support common OAuth 2.0 scenarios such as those for web server, native and client-side applications.
OAuth 2.0 is a relative simple and well documented protocol used by major API providers like Google, Twitter or LinkedIn.
First Step is to obtain OAuth 2.0 crendentials in Developer console.
Then your client App request an access token from WIT-DataCenter Authorization Server, extract token from the response and send the token to WAPI to access an operation.
We suggest you to start with QuickStart tutorial.
Below is detailed a deep overview to communicate with WAPI and WIT-DataCenter Plateform features.
OAuth 2.0 Actors

- Resource Owner: end-user with resources: Flux, Reflexion, etc on WI-DataCenter Plateform
- Resource Server: WAPI
api.wit-datacenter.com
accept and respond to protected resources requests using access token - Authorization Server: WIT-DataCenter authorization server
developer.wit-datacenter.com
issue access token to the client after successfully authenticating the resource owner and obtaining authorization - Client: your Application making WAPI requests on behalf of the resource owner and with its authorization. Client does not imply any particular implementation characteristics: can be web server, native Android, IOS or Windows or batch script...
Register your App
After registering your app, you receive a mail notification with a summary of informations you provided and your App credentials
client_ID
and client_secret
. These credentials identify your App on WIT-DataCenter plateform.
- Client represent your App on WIT-DataCenter Plateform and not an end-user. Report to OAuth 2.0 documentation about Actors The OAuth 2.0 Authorization Framework
- Since each set of credentials is tied to a particular callback URL, you can create different credentials for your development server and production server
- You can retreive your App credentials in Your developed Apps
- Never share your Client credentials with end-users. Do not embed your
client_ID
andclient_secret
in clear in released code or binaries.
Get an Access Token on WIT-DataCenter Authorization Server
You have to choice between 4 OAuth 2.0 Workflows to retreive an access token depending ou yours requirements and App technology.
Code Workflow (= OAuth 2.0 Authorization Code Grant)
Workflow has to be priviliged because it allows to get back arefresh_token
and so do not require a new user authorization on WIT-DataCenter Authorization Server when access token is expired.
Workflow apply to most of Apps type:
- Native Apps: IOs, Android or Windows 8/Phone
- Web Apps server side code
-
Redirect users from your App to WIT-DataCenter Authorization Server :
https://developer.wit-datacenter.com/oauth/authorize? client_id=[YOUR_CLIEND_ID]& response_type=code& redirect_uri=[YOUR_REGISTERED_REDIRECT_URI]& scope=https://api.wit-datacenter.com
Take care to set:client_id
segment by replacing [YOUR_CLIEND_ID] keyword with your App ClientID.redirect_uri
segment by replacing [YOUR_REGISTERED_REDIRECT_URI] keyword with your App callback URL.- Leave other segments unchanged
WarningFor security reasons, YOUR_REGISTERED_REDIRECT_URI must be in same domain as defined in your App Callback property.
Example: if you defined a callback with http://www.myapp.com then YOUR_REGISTERED_REDIRECT_URI can be http://www.myapp.com/wapicallbackmangement but nothttp://www.myapp2.com -
User authenticate on WIT-DataCenter Identity Provider (or WIP) and then autorize (or NOT) App to access your resources on WIT-DataCenter Authorization Server
-
User is then redirect on Callback url you haved defined in
YOUR_REGISTERED_REDIRECT_URI
with a temproraryCODE
in URL QueryString:https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
-
App request definitive autorization token in exchange of temporary
CODE
above. App request with POST :POST https://developer.wit-datacenter.com/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded client_id=[YOUR_CLIEND_ID]& client_secret=[YOUR_CLIEND_SECRET]& grant_type=authorization_code& redirect_uri=[YOUR_REGISTERED_REDIRECT_URI]& code=[CODE]
RemarksYou can test command with CURL:
curl -k -d "client_id=[YOUR_CLIEND_ID]&client_secret=[YOUR_CLIEND_SECRET]&grant_type=authorization_code&code=[CODE]&redirect_uri=[YOUR_REGISTERED_REDIRECT_URI]" https://developer.wit-datacenter.com/oauth/token
-
JSON reponse is an autorization token wich contains
access_token
and other properties:{ access_token: ACCESS_TOKEN; token_type: bearer; expires_in: SECOND; callback: YOUR_REGISTERED_REDIRECT_URI; refresh_token: REFRESH_TOKEN; scope: SCOPE_ALLOWED }
Reponse properties are:Property Description access_token
Access token used to call WAPI opearations token_type
Type de Token: always bearer expires_in
Access Token validity duration in seconds. When your App receive autorization token, you must add this duration to current time to know absolute expiration date. refresh_token
Allow access token refresh when expiration occur Refresh Token. scope
Autorization scope allowed by user. To this day, user can access all WIT-Datacenter Plateform features in limit of their Roles in Account Manager notably
Way of functuioning should change in next roadmap and we will bring some preciseness about App restriction and scope.Until this returned value is https://api.wit-datacenter.com
-
App have now to store autorization token for future use:
access_token
and related properties in your App user store:- For a native App: can be in local cache
-
For a Web App: can be in user related database table
Remark
To store autorization token, user must be identified. You can define a login page or create user account form on App callback url to associate autorization token with your user.
Token Workflow (= OAuth 2.0 Implicit Grant)
This workflow can Apply only if your App technology do NOT allow Code Workflow above. A Javascript App per example.
Workflow imply user authentication and autorization on WIT-DataCenter Authorization Server when access_token
is expired (every one hour) because workflow do not deliver a refresh_token
.
User experience is decreased, so you have to implement this workflow only if techical limitation prevent from Code Workflow.
For a Javascript App you can also use Code Workflow by generating autorization token at server side and delivering access_token
on client Javascript side.
We use this for Rich Internet Application running in browser. Contact WAPI Team if you need more informations on how to perform such workflow.
-
As Code Workflow, redirect users on WIT-DataCenter Authorization Server but
response_type
value is now token.https://developer.wit-datacenter.com/oauth/authorize? client_id=YOUR_CLIEND_ID& response_type=token& redirect_uri=YOUR_REGISTERED_REDIRECT_URI& scope=YOUR_SCOPE [YOUR_SCOPE] = https://api.wit-datacenter.com
-
User is then redirect on Callback url you haved defined in
YOUR_REGISTERED_REDIRECT_URI
with anaccess_token
andexpires_in
in URL QueryString:http://YOUR_REGISTERED_REDIRECT_URI/#token_type=bearer&access_token=ACCESS_TOKEN&scope=SCOPE&expires_in=SECOND
Returned properties in QueryString are:Properties Description access_token
Access token used to call WAPI opearations expires_in
Access Token validity duration in seconds scope
Autorization scope allowed by user
Credential Workflow (= OAuth 2.0 Resource Owner Password Credentials Grant )
Workflow allow direct end-user autentication in your App. App can then exchange user credentials, WIT ID and Paswword with an autorization token.By default this workflow is only available to App owner (developer): we do not autorize end-user to exchange credentials in your App outside WIT-DataCenter Authorization Server for security reasons. Get in touch with WAPI Team if you wich to activate this workflow.
You can use this scenario when just a single user (owner of App) request WAPI in a batch process per exemple to fulfill your own repository
-
Your App must POST
to retreive an authorization:
POST https://developer.wit-datacenter.com/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded client_id=[YOUR_CLIEND_ID]& client_secret=[YOUR_CLIEND_SECRET]& grant_type=password& redirect_uri=[YOUR_REGISTERED_REDIRECT_URI]& username=[YOUR_WITID]& password=[YOUR_PASSWORD]& scope=[YOUR_SCOPE]
- JSON response is same as Code Workflow
-
You can test command with CURL:
curl -k -d "client_id=[YOUR_CLIEND_ID]&client_secret=[YOUR_CLIEND_SECRET]&grant_type=password&username=[YOUR_WITID]&password=[YOUR_PASSWORD]&scope=https://api.wit-datacenter.com" https://developer.wit-datacenter.com/oauth/token
- This workflow is the most simple and is sufficient until you don't need other user to connect on your App
- Workflow is used in QuickStart tutorial
Client Workflow (= OAuth 2.0 Client Credentials Grant)
App request an access token using only its client credentialsClient_ID
and Client_secret
. Returned autorization token response have no user context. App can not request WAPI operation when this context is necessary:-
Your App must POST
to retreive an authorization token:
POST https://developer.wit-datacenter.com/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded client_id=[YOUR_CLIEND_ID]& client_secret=[YOUR_CLIEND_SECRET]& grant_type=client_credentials& scope=[YOUR_SCOPE]
- JSON response is same as Code Workflow
-
You can test command with CURL:
curl -k -d "client_id=[YOUR_CLIEND_ID]&client_secret=[YOUR_CLIEND_SECRET]&grant_type=client_credentials&scope=https://api.wit-datacenter.com" https://developer.wit-datacenter.com/oauth/token
- Most of WAPI operations need a user context so workflow interest is limited to some specifics operations like accessing reference entities: WUMs, Classes
-
Required user context is described in Operation documentation:
Request on WAPI
access_token
and you can call whatever WAPI operation you want on behalf of user (or not if Client workflow).
Your App just have to request WAPI Operation by adding
access_token
and content type JSON / XML / CSV / JSV you need (check WAPI operations for detail).
You have two possibilities:-
Add
oauth_token=ACCESS_TOKEN
etformat=JSON
(or other format) to request:GET https://api.wit-datacenter.com//[WAC]/flux/[FLUXID]?access_token=[YOUR_ACCESS_TOKEN]&format=JSON
-
Or (better) define
access_token
in HTTP header with Authorization: Bearer and formatapplication/json
(or other format) in HTTP header Content-Type:GET /[WAC]/flux/[FLUXID] HTTP/1.1 Authorization: Bearer [YOUR_ACCESS_TOKEN] Content-Type: application/json Host: https://api.wit-datacenter.com/
Operation parameters | Description |
---|---|
WAC | WIT Account number. Example: WAC123456789012 |
FLUXID | ID of Flux |
ACCESS_TOKEN | Access token |
View GetFlux for WAPI Operation description.
You can test command with CURL:
- With Querystring
curl -k https://api.wit-datacenter.com//[WAC]/flux/[FLUXID]?access_token=[ACCESS_TOKEN]&format=JSON
- With HTTP header (really better)
curl -k -H "Authorization: Bearer [YOUR_ACCESS_TOKEN]" -H "Content-Type:application/json" https://api.wit-datacenter.com//[WAC]/flux/[FLUXID]
Refresh an expired access token
access_token
Refresh Token.-
App refresh autorization token by performing this POST
on WIT-DataCenter Authorization Server
POST https://developer.wit-datacenter.com/oauth/token HTTP/1.1 Content-Type: application/x-www-form-urlencoded client_id=[YOUR_CLIEND_ID]& client_secret=[YOUR_CLIEND_SECRET]& grant_type=refresh_token& refresh_token=[YOUR_REFRESH_TOKEN]
RemarksYou can test command with CURL:
curl -k -d "client_id=[YOUR_CLIEND_ID]&client_secret=[YOUR_CLIEND_SECRET]&grant_type=refresh_token&refresh_token=[YOUR_REFRESH_TOKEN]" https://developer.wit-datacenter.com/oauth/token
- JSON response is same as Code Workflow.
- Do not wait access token expiration before refreshing it. Before sending a request on WAPI, just check absolute expiration date and do refresh workflow when expiration is imminent (less than 30 seconds per example)
- Store autorization token in your App store for each end-user:
access_token
,refresh_token
and absolute expiration date (calculate it when you reveive autorization) refresh_token
is updated too when you refresh