AccountBase Address App AppRequest Authorization Building BusinessAccount Country Culture Data DataContainer DataRequestOrder ExtendedProperty ExtendedPropertyValue FileLTU FileLTUContainer FileLTURequestOrder FileStore Flux FluxContainer FluxRequestOrder InfrastructureBase InfrastructureShortBase IRequestOrderBase LTU LTUBase LTUContainer LTUeWon Message Organization Point PointGroup Preparation QuickStart ReflectionAnalogic ReflectionBase ReflectionCommandAnalogic ReflectionCommandBase ReflectionCommandDigital ReflectionCommandDuret ReflectionCommandEwon ReflectionCommandGroup ReflectionCommandGroupContainer ReflectionCommandGroupExecutionSummary ReflectionCommandGroupItem ReflectionCommandGroupPhaseSummary ReflectionCommandMultiple ReflectionCommandPlanning ReflectionCommandState ReflectionCommandSystem ReflectionCommandText ReflectionCommandUnitOfProd ReflectionContainer ReflectionDataAnalogic ReflectionDataBase ReflectionDataContainer ReflectionDataDigital ReflectionDataDuret ReflectionDataEwon ReflectionDataPlanning ReflectionDataState ReflectionDataSystem ReflectionDataText ReflectionDataUnitOfProd ReflectionDigital ReflectionEvent ReflectionEwon ReflectionFormat ReflectionGeneric ReflectionItemAnalogic ReflectionItemBase ReflectionItemDigital ReflectionItemList ReflectionItemText ReflectionParameterAnalogic ReflectionPlanning ReflectionRequestOrder ReflectionState ReflectionStateReference ReflectionSystem ReflectionTemplate ReflectionText ReflectionUnitOfProd Role RoleStatus Site User ValueAnalogic ValueBase ValueDigital ValueText WAC WBase WCAExceptionResource WDCParameter WDCService WEvent WEventCategory WEventItem WEventsContainer WEventsRequestOrder WEventType WUM WUMFunction WUMMaterial WUMType WUMUnit WUMUnitCategory WUMUnitFamily WUMUnitItem Zone
Preferred message format

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.


Four actors are involved in OAuth 2.0 protocol
  • 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...
Start by Registering your App to obtain WAPI credentials.
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.
Remarks
  • 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 and client_secret in clear in released code or binaries.

Access Token allow Apps request WAPI operations and access on WIT-DataCenter resources on behalf of user. Every access token is unique for both user and App. Validatity duration is one hour and can be revoked bu user at any time here Your authorized Apps

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 a refresh_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

  1. 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
    Warning

    For 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 not http://www.myapp2.com

  2. User authenticate on WIT-DataCenter Identity Provider (or WIP) and then autorize (or NOT) App to access your resources on WIT-DataCenter Authorization Server

  3. User is then redirect on Callback url you haved defined in YOUR_REGISTERED_REDIRECT_URI with a temprorary CODE in URL QueryString:
    https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
  4. 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]
                
    Remarks

    You 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
  5. 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

  6. 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.
Warning

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.

Remark

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.


  1. 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
                    
  2. User is then redirect on Callback url you haved defined in YOUR_REGISTERED_REDIRECT_URI with an access_token and expires_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.
Warning

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.

Remark

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

  1. 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]
                
  2. JSON response is same as Code Workflow
Remarks
  • 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 credentials Client_ID and Client_secret. Returned autorization token response have no user context. App can not request WAPI operation when this context is necessary:

  1. 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]
                
  2. JSON response is same as Code Workflow
Remarks
  • 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:

Whoever OAuth 2.0 Workflow you implement, you have now an 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:

  1. Add oauth_token=ACCESS_TOKEN et format=JSON (or other format) to request:
    GET https://api.wit-datacenter.com//[WAC]/flux/[FLUXID]?access_token=[YOUR_ACCESS_TOKEN]&format=JSON
  2. Or (better) define access_token in HTTP header with Authorization: Bearer and format application/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/
                    
Remarks
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:

  1. With Querystring
    curl -k https://api.wit-datacenter.com//[WAC]/flux/[FLUXID]?access_token=[ACCESS_TOKEN]&format=JSON
  2. 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]
Access token have a limited duration before expiration: one hour. Your App receive an invalid token error response when you request WAPI Operation with an expired access token. Before expiration occur, your App have to refresh 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]
                   
    Remarks

    You 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.
Warning
  • 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