Skip to main content

Using OAuth 2.0 to Access the API

Last updated: Mon, 29 Apr 2019 16:25:19 GMT
iOFFICE Knowledge Center

Using OAuth 2.0 to Access the API

The iOFFICE REST API uses the OAuth 2.0 protocol for authentication and authorization. To incorporate the OAuth 2.0 flow into your apps, you will need to contact iOFFICE to provide you with the OAuth 2.0 credentials, such as a client ID and a client secret, that are known to both iOFFICE and your application. The client secret may not be required unless you are building a web server application.

Client-side (JavaScript) applications

AUTHORIZATION CODE

As the user enters your application, the first thing they will need to obtain is an authorization code that will later be exchanged for a token and a refresh token. Redirect the user to a URL that includes five specific query parameters. Refer to the following URL as an example of the format to use.

https://<siteAdress>/login.html?response_type=code&client_id=<id>&redirect_uri=<your_site_that_handles_the_code>&scope=<some_scope>&state=<some_state>

Note: The login.html site will not work correctly if you do not provide the 5 query parameters specified in the example URL.

  1. response_type: This must be set to code.
  2. client_id: This is the ID provided by iOFFICE. This is how our servers recognize the application your users are signing in to.
  3. redirect_uri: This is one of the requirements in order for iOFFICE to generate the client ID and its secret. This is the page in your application that will handle the authorization code.
  4. scope: In the future, we should be able to restrict access of each token by using this parameter. For now, you can set it to email or any other string.
  5. state: This parameter is intended to preserve some state object set by the client.

Entering the URL with correct parameters should open the login screen for the site. After the user successfully identifies with the site, the browser will redirect to the URL provided in redirect_uri with the code provided in the hash parameter. For example:

<redirect_uri>#code=<authorization_code>&appCode=<app_code>

Your JavaScript application needs to read the authorization code and exchange it for an access token and a refresh token.

ALTERNATE AUTHORIZATION CODE REQUEST

If you want to access our API without using a browser, you can also generate an authorization code by requesting it directly. To request an authorization code, make a REST call to:

POST: <ioffice_site>/external/api/oauth2/auth

Include the following header parameters:

'Content-Type': 'application/json',

'x-auth-username': 'user's username',

'x-auth-password': 'user's password',

'x-client-id': '<the client id>'

If successful, the response will be a JSON object with the following information:

"code": string;

ACCESS TOKEN

To request a token, make a REST call to:

POST: <ioffice_site>/external/api/oauth2/token

Include the following header parameters:

'Content-Type': 'application/json',

'x-grant-type': 'authorization_code',

'x-redirect-uri': '<the redirect_uri>',

'x-client-id': '<the client id>',

'x-scope': '<the same scope used to get the auth-code>',

'x-auth-code': '<the auth code obtained in the previous step>',

If successful, the response will be a JSON object with the following information:

token_type: string;

access_token: string;

expires_in: number; // in milliseconds

refresh_token: string;

Make sure to store this information somewhere (localStorage, for instance) since you will need it to make the requests to the API and to obtain new tokens.

Note: The authorization code expires after 5 minutes.

USING THE ACCESS TOKEN

Rest calls use the token either through the query parameter: access_token or the header parameter x-access-token.

For example:

[site]/external/api/rest/v2/users/me?access_token=<access_token>

Each access token has a predefined expiration time. To have continuous access, use the refresh token to obtain a new token.

RENEWING THE ACCESS TOKEN

To obtain a brand new token before or after the token expiration, make another REST call to:

POST: <ioffice_site>/external/api/oauth2/token

Include the following header parameters:

'Content-type': 'application/json',

'x-grant-type': 'refresh_token',

'x-redirect-uri': <the redirect_uri>

'x-client-id': <the client id>,

'x-scope': <the same scope used to get the auth-code>,

'x-refresh-token': <the refresh token>,

This will return a brand new token and another refresh token.

INVALIDATING TOKENS

To invalidate a token, use the endpoint /external/api/oauth2/revoke. The only header needed is:

x-token

This can log out and prevent users from trying to access the API with the token.

  • Was this article helpful?