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
- Sign up for a CORE developer account.
- Enter your email, password and click Sign Up.
- You will receive an email with a confirmation link. Click on that link to complete the registration.
Congratulations! Your developer account is created.
- Go to the CORE Developer Portal.
- Log in to your account with your email address and password.
Add Your Application
- 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 add, update, and delete your apps from your dashboard.
- On the dashboard, click Add New Application.
- Choose your application name, application type and redirect URI. Enter the description of your application and then click Create.
- 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.
Get Your Client ID and Secret Key
Your app needs OAuth keys in order to make a secure connection with CORE. When you create your app, you must include the keys and tokens to get going.
- From your CORE Developer Portal , click on app details button.
- 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
CORE APIs use the OAuth 2.0 protocol. It is simple and more straightforward to use for authentication and authorization. Developers can start using the APIs almost immediately.
CORE APIs require 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. In order to obtain an access token, your app needs users to log in with their CORE company credentials and grant the requested permissions. Because the access tokens have an expiry time, your app needs a new access token every time the old one expires. You can get a new access token by repeating the authorization steps and asking the users for consent again or you can use a refresh token to get a new access token behind the scenes. This bypasses the need to repeatedly ask the users for consent. 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 users to our authorization URL.
GET /connect/authorize?client_id=Q3ylJatCvnkYqVKLmkH1zWlNzNWB5CkYB36b5mws7HkKUEv9aI&response_type=code&scope=readwrite:core&redirect_uri=https://coredemo.com/Where:
| Parameter | Values | Description |
|---|---|---|
| client_id | The Client ID you obtain from the developer dashboard | Required. 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 |
| scope | Space-delimited set of permissions that the application requests | Required. 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: |
| redirect_uri | One 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_type | code | Required. Determines whether CORE API OAuth 2.0 endpoint returns an authorization code. Always set this to the code |
| state | This field can be a Base64 encoded JSON object that can hold multiple values | Authorization 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). Users are taken to the CORE Log In screen and enter their CORE company credentials here.
Step 1(b). CORE displays a consent dialog to the users with the name of your application, requesting permission to access data. Users can modify the scope requested by your application and also select the CORE company, in case a user has multiple companies.
Step 1(c). When done, the users click on Grant Permission to grant the selected permissions to your app. If a user allows offline_access on this page, you have the option to use the refresh token to keep the user signed-in indefinitely without having to ask for consent again.
CORE does not allow users to log-in to multiple companies from a single client app instance.
Step 2: Receive the redirect from CORE APIs.
After a user authorizes your application, we issue a redirect to your redirect_uri with a code parameter.
http://yourdemoapp.com?code=CODEThe 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 URI | REDIRECT_URI PARAMETER PASSED TO /AUTHORIZE | VALID? |
|---|---|---|
| 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:
| Parameters | Description |
|---|---|
| error | Access denied |
| error reason | The user did not authorize the request |
| invalid scope | An 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 token endpoint "POST /connect/token".
These are the required parameters:
| Parameters | Description |
|---|---|
| code | Required. The authorization code returned from the initial request |
| redirect_uri | Required. One of the redirect URIs listed for this project in the developer dashboard |
| grant_type | Required. As defined in the OAuth 2.0 specification, this field must contain a value of authorization_code |
| client_id | Required.This is your application's Client ID |
| client_secret | Required. 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:
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.
- When you make a POST request to the token endpoint, in addition to the access_token and refresh_token, you also receive the endpoint in the response.
/connect/tokenThis 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-8ResponseIf 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.