Getting Started

Getting started with new APIs can be challenging. To simplify the process, we have created a systematic guide that walks you through the process of creating a Core Developer account and much more. You can also watch our tutorials.

Create a Core Developer Account

  1. Sign up for a Core developer account.
    Developer Portal Signup
  2. Enter your email, password and click Sign Up.
    Confirm Developer Account
  3. You will receive an email with a confirmation link. Click on that link to complete the registration.
    Email Confirmation

    Congratulations! Your developer account is created.

  4. Go to the Core Developer Portal.
  5. Log in to your account with your email address and password.

Create Your Application

  1. After logging in, you will be taken to the Core Developer Portal dashboard.
    The Dashboard is your home page that displays when you log in to Core Developer Account. All your apps and their credentials rest here. You can create, update and delete your apps from your dashboard.
    Create New Application
  2. On the dashboard, click Add New Application.
  3. Create New Application
  4. Choose your application name, application type and redirect URI. Enter the description of your application and then click Create.
    Create New Application
  5. You will be prompted to copy your client secret key. Click OK to complete.

    The client secret is only generated when your app type is web. The key generated above is for illustration only. It SHOULD NOT be used in an application.
    Create New Application

Get Your Client ID and Secret Key

Your app needs OAuth keys in order to make a secure connections with Core. When you create your app, you must include the keys and tokens to get going.

  1. From your Core Developer Portal , click on app details button.
    Create New Application
  2. The app displays the dashboard with your App Name, Client ID and Description. From the Developer Portal dashboard, you will be able to manage your apps, keys and other things.

    In case your application type is web, you can generate a new client secret key. Go to the dashboard screen, choose the web application for which you want to generate a new client secret, click on app details button and click on Generate New.

Get Access Token

The Core API uses the OAuth 2.0 protocol. It is simple and more straightforward to use for authentication and authorization. Developers can start using the Core API almost immediately.

All requests to the API must be made over SSL (https://) and not (http://).

The Core API requires authentication on all requests made on behalf of a user. Authenticated requests require an Access Token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future. To know more check out Tokens.

Server-Side Flow

Initiate the OAuth 2.0 process by redirecting the user to the Core authentication server. To obtain access to the Core API resources, you will require an Access Token. To receive the token, follow the steps given below:

Step 1: Direct your user to our authorization URL.

GET /connect/authorize?client_id=Q3ylJatCvnkYqVKLmkH1zWlNzNWB5CkYB36b5mws7HkKUEv9aI&response_type=code&scope=readwrite:core&redirect_uri=https://coredemo.com/

Where:

ParameterValuesDescription
client_idThe Client ID you obtain from the developer dashboardRequired. Identifies which app is making the request. Obtain this value from the Keys tab on the app profile via My Apps on the developer site
scopeSpace-delimited set of permissions that the application requestsRequired. Identifies the Core API access that your application is requesting. The values passed in this parameter inform the consent screen that is shown to the user

Available scopes include:
read:core- Read only access to company data
readwrite:core- Full access to company data
offline_access - To recieve a Refresh Token
openid- Provides access to a user's details like name, address, etc.
profile- Provides access to a user's profile excluding address and email
address- Provides access to the address claim at the UserInfo endpoint
email- Provides access to the email claim at the UserInfo endpoint

redirect_uriOne of the redirect URI values listed for this project in the developer dashboard.Required. Determines where the response is sent. The value of this parameter must exactly match one of the values listed for this app in the app settings. This includes the https scheme, the same case
response_typecodeRequired. Determines whether Core API OAuth 2.0 endpoint returns an authorization code. Always set this to the code
stateThis field can be a Base64 encoded JSON object that can hold multiple valuesAuthorization protocols provide a state parameter. During authentication, the application sends this parameter in the authorization request, and the Authorization Server will return this parameter unchanged in the response. Your application can use this parameter in order to make sure that the response belongs to a request that was initiated by the same user. Therefore, state helps mitigate CSRF attacks.
Restore the previous state of your application

You may provide a scope parameter to request additional permissions outside of the "basic" permissions scope.
You may provide an optional state parameter to carry through a server-specific state. For example, you can use this to protect against CSRF issues.

Step 1(a). You will be taken to the Core user Log In screen.

Create New Application

Step 1(b). Enter your Core credentials to authenticate. Core displays a consent dialog with the name of your application and Core Company name, requesting permission to access with your authorization credentials including scope, etc

Create New Application

Step 1(c). Select the permissions allowed and click on Yes to allow permissions to your app.

Core does not allow you to log-in to multiple companies during a single client app instance. If you have more than one company, click on the check box of the company you are giving access to.

Step 2: Receive the redirect from Core API.

After a user authorizes your application, we issue a redirect to your redirect_uri with a code parameter.

http://yourdemoapp.com?code=CODE

The host and path components of your redirect URI must exactly match (including trailing slashes) your registered redirect_uri. You may also include additional query parameters in the supplied redirect_uri, if you need to vary your behavior dynamically. You can check out the examples given below:

REGISTERED REDIRECT URIREDIRECT_URI PARAMETER PASSED TO /AUTHORIZEVALID?
http://yourcallback.com/ http://yourcallback.com/ yes
http://yourcallback.com/ http://yourcallback.com/?this=that yes
http://yourcallback.com/?this=that http://yourcallback.com/             no
http://yourcallback.com/?this=that http://yourcallback.com/?this=that&another=true yes
http://yourcallback.com/?this=that http://yourcallback.com/?another=true&this=that no
http://yourcallback.com/callback http://yourcallback.com/ no
http://yourcallback.com/callback http://yourcallback.com/callback?type=mobile yes

However, if your request is denied by the user, then we will redirect the user to your redirect URI with the following parameters:

ParametersDescription
errorAccess denied
error reasonThe user did not authorize the request
invalid scopeAn invalid scope string was sent

Step 3: Request the Access Token

Now you need to exchange the code you have received in the previous step for an access token. In order to make this exchange, you simply have to POST this code to our Access Token endpoint "POST /connect/token".

Request

These are the required parameters:

ParametersDescription
codeRequired. The authorization code returned from the initial request
redirect_uriRequired. One of the redirect URIs listed for this project in the developer dashboard
grant_typeRequired. As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code
client_idRequired.This is your application's Client ID
client_secretRequired. This is your application's Client Secret (only required for confidential applications)

If successful, this call will return a neatly packaged token that you can use to make authenticated calls to the Core API resources. The response will contain the following fields:

Response

Refresh Token will be returned only if you have included the offline_access scope when you initiate an authentication request through the authorize endpoint.

Base URL

In the Core API Reference documentation, each API call shows the REST method, path, resource, and parameters that must be appended to the base URL to form a request.

BQE Core supports multiple data centers and the endpoint allows you to interface with Core regardless of the place you are accessing it from.

Validate your base URL before making any API calls. If you do not validate, your API calls might not work.
  • When you make a POST request to the Access Token endpoint. In addition to the Access Token and Refresh Token, you also receive the Endpoint in the response.

    /connect/token

    This endpoint is your Base URL. For more details, see authentication

  • If you receive a successful response, the response body will look like:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8

    If you receive a failure response, the response body will look like:

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=utf-8
    Content-Length: 20
    "Not authenticated"

  • Now that you have the Base URL, use it to make calls to our APIs.

    In the above example, you would use “endpoint”: “https://xxx.bqecore.com/xxx/" as the Base URL for any API calls you make to Core.


Make Your First Request

After your application obtains an Access Token, you can use it to make calls to the Core API resources. To do this, include the Access Token in the request to the API by adding it in the authorization: Bearer HTTP header.

Pass in a custom header with key X-UTC-OFFSET with offset as value (in minutes). If no such header is passed, a default of Pacific Standard Time is assumed.

Example: A call to the Activity endpoint to read a given object using the Access Token parameter.

Request