Using OAuth 2.0 to Access the API
The Eptura Workplace 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 Eptura to provide you with the OAuth 2.0 credentials, such as a client ID and a client secret, that are known to both Eptura Workplace 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.
- response_type: This must be set to code.
- client_id: This is the ID provided by Eptura. This is how our servers recognize the application your users are signing in to.
- 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.
- 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.
- 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.