Logo
My activities

Resolver Core API - Getting Started

What is the Core API?  

The Resolver Core API is a set of web services that allow you to control Core from a third-party application. The API is the only method through which the application’s UI communicates with Core’s services.

What does the API offer?

The API offers a complete set of functionalities for the application. Everything that can be done through the Core user interface can be achieved (with varying amounts of difficulty) through the API. The API can be explored and tested through Swagger, a web-based API browser.

The Swagger page is accessible from inside Core under Settings > Tools:

mceclip0.png

or directly at:

https://YOUR_ENVIRONMENT.resolver.com/api?

 

Swagger provides a complete list of all the Core APIs along with some details of the expected usage and response payloads, allowing you to test out the API calls without having to use a browser or another tool.

mceclip1.png

Our Swagger documentation is still a work in progress, but it continues to improve with every release.

What technology does the API use?

The Core API is a RESTful web service that leverages JSON for both request and response payloads. Some URLs include inline parameters or query parameters, while some URLs take POST payloads to execute. The HTTP verbs GET, PUT, POST, and DELETE are used throughout the API where appropriate.

Is the API available to all customers?

The API is available to all Resolver Enterprise and Professional customers.

Do I need a special license to use the API?

No.

Are there any limitations or restrictions when using the API?

If you can perform the action through the UI, that same action can be performed via the API. However, some actions may involve numerous API calls or complex payloads and may require assistance from Resolver Support.

How do the API security and authentication processes work?

There are two methods of authenticating to Core:

API Token

Authentication via API Token is the preferred method in almost all circumstances. Any Core admin can generate an API Token for their org. Once generated, including the token in the request header of an API call is all that is required to authenticate to Core.

An API Token is generated for a user in an org. All API calls made using the token will be executed against that org, and with that user's permissions.

API Tokens never expire, and do not need to be renewed.

When making an API call, include your API Token in the request header using the x-api-key parameter

x-api-key: YOUR_API_KEY

Example

Request:

Call the Who Am I? endpoint to return details about the currently logged in user and org:

mceclip2.png

curl -X GET --header 'Accept: application/json' --header 'Accept: application/json' --header 'x-api-key: YOUR_API_KEY' 'https://sandbox.resolver.com/user/users/me'

Response:

Response containing user and org details:

{
"id": 19732,
"first": "API",
"last": "User",
"email": "api.user@coreqe.com",
"modified": "2020-02-03T18:32:56.707Z",
"externalRefId": "d377fbe9-cfe9-45dd-bd2a-57a3fdc19fd7",
"isAdmin": true,
"superAdmin": false,
"acceptedTos": true,
"lastLogin": "2020-02-03T18:32:56.707Z",
"ssoBypass": false,
"lang": "en-US",
"isActive": true,
"allAccess": true,
"currentOrg": {
"id": 973,
"name": "Bryan - Test",
"passwordExpiration": 90,
"logoUrl": "https://resolver-core-sandbox-sandbox-upload.s3.ca-central-1.amazonaws.com/org_973/ff6d16f8-dea7-4c88-8b20-9422b9434ed6.png",
"infrastructureId": 1,
"maintenanceContext": null,
"maxUsers": null,
"biConnectorEnabled": true,
"disablePendoPii": false
}
}

Login + Session Token

A second authentication option is to log in to Core with user account credentials. This option is substantially more complicated than using an API Token, but can be useful when creating a general-purpose tool for use on any org. Since an API Token is tied to a user in an org, it may not be practical to generate an API token for every org you are expecting to access.

Important Considerations:

  • Successful authentication requires a valid password, and account passwords expire based on the org's configured password policy. Using login authentication for a static integration is not recommend for this reason.
  • Authentication via login as multi-step process.
  • Upon successful authentication, Core will return a Json Web Token (bearer token). This token is valid for 15 minutes. To extend the session, the token must be refreshed before the 15 minutes has expired. Tools that perform long operations may require a child thread to guarantee that the token refresh window is not missed.
  • While logging in with Core credentials is a set process, logging in with SSO may not be:
    • When a user is already authenticated by their IdP (for example, by being logged into their corporate network) handling the SSO exchange is fairly simple.
    • When a user is not already authenticated, the authentication process then depends on the IdP, and the login process must be customized accordingly. For example, on ADFS and Azure, users outside the corporate network are generally redirected to a login web page. Your tool would need to be customized to handle credential submission through this page, and receiving and passing the IdP's response back to Core.

Logging In with Resolver Core user credentials

Note: SSO examples are outside the scope of this article. For assistance please contact Resolver Support.

Call:

mceclip4.png

POST https://YOUR_ENVIRONMENT.resolver.com/user/authenticate 

passing in the user's credentials and the org ID in json format in the request body:

{
"email": "YOUR_EMAIL",
"password": "YOUR_PASSWORD"
"selectedOrg": DESIRED_ORG_ID
}

Possible responses:

Response Reason
401 Unauthorized bad credentials
404 Not Found user is not an active member of any orgs
200 success

 

Example

Request:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "email": "api.user@coreqe.com",
  "password": "&P9n#wBKketKYdQ@qoi1",
  "selectedOrg": 973
}' 'https://sandbox.resolver.com/user/authenticate'

Core will respond with a json payload including the bearer token to be used for subsequent calls. This token is valid for 15 minutes.

Response:

{
"token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJzZXNzaW9uIjoiN2I1Nzg5OGItYzhjNC00MzFkLThhZjctY2MwMzQ1NGI3OGQ5IiwiX3B1cnBvc2UiOiJsb2dpbiIsImV4cCI6MTU4MDc3Mjc3NiwiaWF0IjoxNTgwNzU0Nzc2fQ.AQICAHgPjufvtghndUvcYMwgWWc8i9Bs5NNytmOBXL3Iyn1EwwGU2HMlxo5uTEzAqNQNoMH4AAABETCCAQ0GCSqGSIb3DQEHBqCB_zCB_AIBADCB9gYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAxnTbYA04yq1Z-PA3wCARCAgcgHcGaq8JRw3oK4-4TcikGLtZPMENq-iUc6H22mJPi-vUKSb7wA8_LRa69CZiOc24tVZZ99Blg8y53pqM5mFTgjkGWKWDMjzOfGLyonzgNfewl_jW5KT9434QlRTE76ZipcvyP9OjxvigEqDsSHu7ugOTfX8qian5qyZsO_1KolcE4NMKEBZZ26u21o0LeI7bGLwjc6Y9DZXI9syIfOTuzyvEbzBHk3syQDvy-ZAYZYuyMwjZgjtzUx4x6hFwVt5s-Mdsr0ES0ZZg",
"expiresAt": 1580772776,
"user": {
"scope": [
"user",
"admin"
],
"id": 19732,
"first": "API",
"last": "User",
"email": "api.user@coreqe.com",
"modified": "2020-02-03T18:14:14.007Z",
"externalRefId": "d377fbe9-cfe9-45dd-bd2a-57a3fdc19fd7",
"isAdmin": false,
"superAdmin": false,
"acceptedTos": true,
"lastLogin": "2020-02-03T18:14:14.007Z",
"ssoBypass": false,
"lang": "en-US"
},
"isAdmin": true,
"logoUrl": "https://resolver-core-sandbox-sandbox-upload.s3.ca-central-1.amazonaws.com/org_973/ff6d16f8-dea7-4c88-8b20-9422b9434ed6.png",
"language": "en-US",
"activeOrg": 973,
"orgModel": {
"id": 93768,
"userId": 19732,
"orgId": 973,
"isActive": true,
"allAccess": true,
"created": "2020-02-03T18:01:12.366Z",
"modified": "2020-02-03T18:01:12.366Z",
"deleted": null,
"excludeFromMembershipCount": false,
"orgName": "Bryan - Test",
"passwordExpiration": 90,
"logoUrl": "https://resolver-core-sandbox-sandbox-upload.s3.ca-central-1.amazonaws.com/org_973/ff6d16f8-dea7-4c88-8b20-9422b9434ed6.png",
"maintenanceContext": null,
"disablePendoPii": false,
"isAdmin": true
}
}

 

Subsequent Calls

After login, you must include a valid bearer token the authorization header of every request:

Authorization: bearer <YOUR_BEARER_TOKEN>

Example

Request:

Call the Who Am I? endpoint to return details about the currently logged in user and org:

mceclip2.png

curl -X GET --header 'Accept: application/json' --header 'Authorization: bearer <YOUR_BEARER_TOKEN>' 'https://sandbox.resolver.com/user/users/me'

Response:

Response containing user and org details:

{
"id": 19732,
"first": "API",
"last": "User",
"email": "api.user@coreqe.com",
"modified": "2020-02-03T18:32:56.707Z",
"externalRefId": "d377fbe9-cfe9-45dd-bd2a-57a3fdc19fd7",
"isAdmin": true,
"superAdmin": false,
"acceptedTos": true,
"lastLogin": "2020-02-03T18:32:56.707Z",
"ssoBypass": false,
"lang": "en-US",
"isActive": true,
"allAccess": true,
"currentOrg": {
"id": 973,
"name": "Bryan - Test",
"passwordExpiration": 90,
"logoUrl": "https://resolver-core-sandbox-sandbox-upload.s3.ca-central-1.amazonaws.com/org_973/ff6d16f8-dea7-4c88-8b20-9422b9434ed6.png",
"infrastructureId": 1,
"maintenanceContext": null,
"maxUsers": null,
"biConnectorEnabled": true,
"disablePendoPii": false
}
}

Token Refresh

To maintain the current session, call

mceclip5.png

GET https://services.core-ca.resolver.com/user/authenticate 

passing in the current token in the Authorization header (as with other requests). Doing so will provide a payload with a new token, which is valid for an additional 15 minutes. If no token renewal is performed after 15 minutes, the session is terminated.

Example

Request:

Request new token:

curl -X GET --header 'Accept: application/json' --header 'Authorization: bearer <YOUR_BEARER_TOKEN>' 'https://sandbox.resolver.com/user/authenticate'

Response: 

Response containing new bearer token:

{
"token": "eyJhbGciOiJLTVMiLCJ0eXAiOiJKV1QifQ.eyJzZXNzaW9uIjoiOTMzNTRkYWQtMWU3ZC00YjVmLThiZDAtMGQzM2VjNWE2Yjc1IiwiX3B1cnBvc2UiOiJsb2dpbiIsImV4cCI6MTU4MDc3MTIxNiwiaWF0IjoxNTgwNzUzMjE2fQ.AQICAHgPjufvtghndUvcYMwgWWc8i9Bs5NNytmOBXL3Iyn1EwwE4Job8qX9SyTCjAynM939HAAABETCCAQ0GCSqGSIb3DQEHBqCB_zCB_AIBADCB9gYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAxl5EBn0ywSQOp8uKMCARCAgchs24fH44q0ST4qRdJkxBStvglZqhkAXizvVq53-TXOQyA4O2dLnO7RhzsZw5JKLcwqPkcaTtQAbanpbgdei_OUaDiQsIZAzJwOejoKJIiLvP_F-t0qMfJr44eezc2JpIbxL--QT85U7S5ef3HJjh9pZAHYgWLVmXX14FwFqwwEjtMb9HukLtI9olb2DnOfX6uSwJ-7pmaybPCrxVpcDS5z77Fr-IP82K8oWlO5dtfM1NlSY-SrF80BftbuBQsGiiM6RVLq112Usw",
"expiresAt": 1580771216,
"user": {
"id": 19732,
"first": "API",
"last": "User",
"email": "api.user@coreqe.com",
"modified": "2020-02-03T18:06:13.234Z",
"externalRefId": "d377fbe9-cfe9-45dd-bd2a-57a3fdc19fd7",
"isAdmin": false,
"superAdmin": false,
"acceptedTos": true,
"lastLogin": "2020-02-03T18:06:02.825Z",
"ssoBypass": false,
"lang": "en-US"
},
"isAdmin": true
}

 

 

 

Follow
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Powered by Zendesk