Using OAuth 2.0 to Access the API

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 Eptura. 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 Eptura Workplace 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>',

'x-redirect-uri': '<redirect_url>,

'x-scope': '<scope>'

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 through the header parameter Authorization.

For example:

curl -X GET -H "Authorization: Bearer [ACCESS_TOKEN]" [site]/external/api/rest/v2/users/me

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.