Getting Started
Getting started with new APIs can be challenging. To get you up and running quickly, let’s cover all the basics: creating your developer account, adding your application to it, implementing the authorization flow, understanding your Redirect URI, and making your first API call. If you know these fundamentals, you are ready to develop apps that integrate CORE APIs into your own workflows.
CORE APIs use the OAuth 2.0 protocol to securely authenticate and authorize your apps. For the complete protocol definition and security considerations, refer to the OAuth 2.0 specification in RFC 6749. Be sure to check out our detailed Authentication and Authorization page as well.
Create Your CORE Developer Account
To begin using CORE APIs, you need to create a developer account in the CORE Developer Portal.
CORE Developer Portal is a central hub for managing all aspects of your CORE API access. From here, you can set up and log in to your developer account, add and configure your apps, and even set up webhooks. You will also find links to useful resources such as our API Documentation, Swagger Try-Out, FAQs, sample apps on GitHub, and Discovery Document.
To create your developer account, follow the steps below or watch this video.
- On the Developer Portal homepage, click Sign Up.
- On the CORE Developer Signup page, click Get Started.
- On the Sign Up tab, enter the required details including your name, email address, etc. and a strong password.
If you are a CORE user, note that the developer account is separate from your CORE account. You can create a developer account using any email address. It does not need to be the same email address you use to log in to CORE.
- Make sure you read and agree to the Developer Agreement before clicking Sign Up.
- CORE will send an activation link to your email.
- Click on the link to finish the account setup.
Congratulations! Your developer account is now ready.
Creating a developer account and adding apps to it is free. However, your apps can only interact with data from CORE companies that have a valid, paid subscription.
Add Your Application
After creating a developer account, you need to add your application to it. Adding your app means registering it with the CORE APIs Authorization Server as a valid client that can initiate the authorization required to access and use CORE APIs. After you add an app, CORE generates OAuth keys (Client ID and Client Secret) for it, which are required to initiate the OAuth 2.0 authorization flow.
You can add multiple apps to your account, each with its own unique configuration.
To add an app to your CORE developer account and retrieve the OAuth keys, follow the steps below.
- Log in to your developer account from the Developer Portal homepage.
- On the Dashboard, click Add New Application.
The Dashboard is your account’s homepage that displays right after you log in. All your apps and their configurations are listed here. You can add, configure, and delete apps from here as needed.
- On the Add New Application dialog, enter the required details: your Application Name, Application Type, one or more Redirect URIs, and a Description. Optionally, enter one or more Post Logout Redirect URIs.
You can register your app as a server-side Regular Web App, a Native App, or a single-page JavaScript App. The OAuth 2.0 authorization flow can vary for the different app types. Check out the Authentication and Authorization page for details.
Redirect URI is the exact URL set in your app where CORE APIs send users after they complete the OAuth 2.0 authorization flow. Check out the Understanding your Redirect URI section on this page for details.
The Post Logout Redirect URI is the URL set in your app where the users are redirected to after being logged out of the CORE session.
You can add multiple Redirect URIs for your app by clicking the button.
- Click Create to finish adding your app.
- You are prompted to copy the secret key (Client Secret) and keep it safe. Click on the key to copy it and then click OK to return to the Dashboard.
Client Secret is a confidential key used by your app to prove its identity to the Authorization Server during the authorization process. It is only generated when your Application Type is Regular Web App and is never to be exposed publicly. Make sure you save it somewhere safe.
- You can see your app listed on the Dashboard.
- Open the app details by clicking the App Details icon or anywhere on the app accordion.
- In the app details, you can see the Client ID of the app. Click on it to copy it and then save it somewhere safe.
Client ID is a public identifier for your app issued by the Authorization Server. It is used during the authorization flow as explained in the next section.
You can generate a new Client Secret for your web-type apps. To do so:
- Click the Edit icon on an app to open the Edit App Setting dialog.
- Click Generate New next to Client Secret to generate a new secret.
- Like before, copy it and save it somewhere safe.
Now that you have set up and configured your app, let’s look at how you can implement the OAuth 2.0 authorization flow.
Implement Authorization Code Flow
To securely access CORE APIs, your apps must implement the OAuth 2.0 Authorization Code flow. This allows your apps to authenticate CORE users and obtain access tokens without ever seeing or storing their credentials.
All requests to CORE APIs must be made over HTTPS. Requests over insecure HTTP are rejected.
CORE APIs only support the Authorization Code and Refresh Token grant types. Other OAuth 2.0 grant types, such as Implicit, Client Credentials, and Resource Owner Password Credentials, are not supported.
In the Authorization Code flow, your app needs to guide users to a secure CORE Log In screen where they enter their CORE company credentials. After logging in, the users are presented with a consent screen where they need to grant the requested permissions to your app. After they grant the consent, your app receives an authorization code which it can then exchange for an access token.
Access token is a short-lived credential that your app requires to authorize all API requests made on a user’s behalf. It is unique to each user and your app must store it securely.
Every time an access token expires, your app needs a new one. For that, your app can either guide the user through the login process again or use a refresh token to silently get a new access token without having to repeatedly ask the user for consent. Check out the Tokens page to learn more.
Now let’s walk through how your app can implement the Authorization Code flow in practice. This involves a series of interactions between your app, CORE Authorization Server, and the user. Assuming your app’s type is Regular Web App, the typical steps to be implemented in the flow are listed below.
For other app types, refer to the Authentication and Authorization page.
Step 1: Construct the Authorization URL and redirect to it
To initiate the OAuth 2.0 process, your app must construct the following URL and direct the users to it:
GET /connect/authorize?client_id=Q3ylJatCvnkYqVKLmkH1zWlNzNWB5CkYB36b5mws7HkKUEv9aI&response_type=code&scope=readwrite:core&redirect_uri=http://yourcallback.com/The request is sent to the CORE Authorization Server and can include the following query parameters:
| Parameter | Values | Description |
|---|---|---|
| client_id required | Your app’s Client ID | Identifies the app making the request. Use the value from your app’s details in the Developer Portal Dashboard. |
| scope required | Space-delimited set of permissions that the app is requesting | Specifies what level of access your app is requesting. The values passed in this parameter inform the consent screen shown to the users. Available scopes include: |
| redirect_uri required | One of the Redirect URIs registered for your app | Specifies where the Authorization Server should send the response. The value must match exactly (including scheme, host, path, case, and any trailing slashes) with one of the Redirect URIs registered for your app in the Developer Portal. Otherwise the authorization request is rejected and the users see an error page. Check the Understanding your Redirect URI section on this page for details. |
| response_type required | code | Indicates the type of response your app expects. For Authorization Code flow, this must always be ‘code’, meaning your app expects to receive an authorization code. |
| state | Base64-encoded JSON object that can hold multiple values | An optional value your app can send in the authorization request. It is returned unchanged by the Authorization Server, allowing your app to verify that the response is tied to the original request. This can help with preventing Cross-Site Request Forgery (CSRF) attacks. |
Your app must request at least one of the basic scopes (read:core, readwrite:core, or openid) in the authorization requests. In addition to the basic scopes, it can request offline_access to receive a refresh token. Furthermore, the profile, address, and email scopes require openid to be requested as well. If any of these conditions are not satisfied, the authorization request fails with an invalid_scope error.
When directed to the Authorization URL, the users see a secure CORE Log In screen where they need to enter their CORE company credentials.
After logging in, users see a consent screen showing your app’s name and the level of access it is requesting (based on the scope parameter). They can adjust the requested permissions and also choose the CORE company to give access to, in case a user has multiple companies.
On the consent screen, the users can click Grant Permission to grant the selected permissions to your app or Decline to refuse access.
If a user allows the Offline Access permission on the consent screen, your app will receive a refresh token in addition to the access token. You can use the refresh token to keep the user signed-in indefinitely without having to ask for consent again.
When the users grant permission, the Authorization Server redirects them back to your app’s Redirect URI with an authorization code appended. Your app then needs to capture this code to continue the OAuth flow.
While the users log in and grant the permissions, your app is in a waiting state – ready to receive the authorization code via the redirect URI after the user interaction is complete and consent is granted.
Step 2: Receive the redirect from the Authorization Server
After a user grants consent to your app, the Authorization Server redirects the user to your app’s registered Redirect URI with an authorization code included as a query parameter:
http://yourcallback.com?code=CODEHowever, if a user declines on the consent screen, the Authorization Server redirects the user to the Redirect URI with the following parameters.
| Parameters | Description |
|---|---|
| error | access_denied |
| error reason | The user did not authorize the request |
Step 3: Exchange the authorization code for an access token
After receiving the authorization code, your app must exchange it for an access token by sending a POST request to the CORE APIs token endpoint:
The request includes the following parameters:
| Parameters | Description |
|---|---|
| code | Required. The authorization code received in Step 2 |
| redirect_uri | Required. One of the Redirect URIs registered for the app in the Developer Portal |
| grant_type | Required. Must be ‘authorization_code’ for this flow |
| client_id | Required. Your app's Client ID |
| client_secret | Required. Your app's Client Secret (only required for confidential apps) |
You obtain the Client Secret when adding your app on the Developer Portal as explained in the Add Your Application section on this page.
A successful 200 OK response to the request returns the following JSON object that includes the access token, along with other fields such as the ID token, access token expiry time, refresh token, scopes granted, and endpoint.
The response includes a refresh_token and an id_token only if your app requested and was granted the offline_access and openid scopes, respectively.
A failure 4XX response to the token request returns a reason for the failure in the body, e.g., invalid_request, invalid_client, invalid_grant, etc.
The endpoint field you receive in the successful response is your Base URL for all subsequent API calls. Be sure to validate this URL before making any requests, as it can vary by data center. You can use this URL and the access token to create your first API request as explained in the Make Your First API Call section on this page.
Understand your Redirect URI
The Redirect URI (also called the callback URL) is the endpoint in your app where CORE Authorization Server sends the users after they log in and grant (or deny) access. It is a critical security measure in the OAuth 2.0 flow. You can add one or more Redirect URIs when registering your app on the Developer Portal. You must then ensure that you use an exact match of one of those URIs as the redirect_uri parameter in the /authorize request during the OAuth flow.
What is Redirect URI: A URL you define in your app that handles the incoming authorization code during the OAuth flow.
Why you need it: By pre‑registering this URI in the Developer Portal and then using its exact match in /authorize requests, it is ensured that authorization codes are only ever sent to approved locations, preventing malicious interception.
Exact Match Requirements
The host and path of the redirect_uri you send in the authorization request must exactly match one of the Redirect URIs you registered on the Developer Portal. This includes the URL scheme, domain, path, trailing slash, and case. Otherwise, the authorization request fails and the user sees an error page. You can append extra query parameters at runtime if you need to vary your behavior dynamically, but the base structure must match.
The following table shows examples of valid and invalid redirect_uri values.
| 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 |
Make Your First API Call
After your app has obtained an access token, it can call any CORE API resource endpoint by including the token in an HTTP Authorization: Bearer header and using the Base URL provided in the token response’s endpoint field.
By default, CORE APIs interpret dates and times in Pacific Standard Time. To use a different time zone, include the X-UTC-OFFSET header in your requests with value as your offset in minutes.
Example
Let’s retrieve a specific activity item by calling the Retrieve an Activity endpoint. Make sure you replace base_url with the endpoint field you received in the token response and [YOUR_ACCESS_TOKEN] with a valid access token.
You can now use this pattern to call any other CORE API resource endpoint. Simply adjust the URL path, request body, and parameters as needed. Be sure to check out the API Reference pages to see all the available API resource endpoints.