API Authentication

API Key Overview

API keys are used to authenticate requests to the Resolver Core API without entering user credentials.

Important Notes

  • API keys never expire, with no need to establish or maintain a session.
  • API keys are tied to the user's org account. This means that if a user doesn't have permission to perform an action in Core, they won't be able to do it through the API.
  • Only admins and super admins can create API keys. Admins can only create keys for orgs on which they're an admin.
  • It's possible to create API keys to impersonate other users; however, only super admins can enable this feature. See the Impersonation section of Use an API Key for article for more information.
  • Only active users of the same org as the API key user can be impersonated.
  • Any call can be made using an API key while impersonating another user; however, only three endpoints in the Swagger user interface support this: This was written rather ambiguously in the original article, so I'm not sure if he's referring to impersonation, using API keys, or both. I think it's the combination of both.
    • POST /data/file/file in the file resource;
    • POST /data/object/{objectID}/file/{fileID} in the object resource; and
    • POST /creation/import/json in the dataImport resource.
  • For security purposes, API keys are not stored. If you misplace the key, it cannot be retrieved and must be regenerated.

See the following articles for more information and instructions:

Create an API Key

To create an API key:

  1. Review the Important Notes section in the API Key Overview article.
  2. Login as an admin and select the appropriate org, if required.
  3. Click theicon in the top bar > Users in the People section.
  4. Click Create User.
  5. Enter the user's name in the First Name and Last Name field.
  6. Enter an email address in the Email field. If the API key is for a production environment, enter a valid company email address.
  7. From the Edit User page, click the icon next to All Access to allow the user to view, edit, and delete all data in the org. Alternatively, you may add the user to a role or user group.
    The Create User page.
  8. Optional: Click the icon next to Admin to enable administrative rights.
    For added security, it's recommended that the Admin setting is not enabled for API users unless admin privileges are needed to complete the required API calls.
  9. Click Create.
  10. From the Edit User page, record the account's internal ID from the address bar of your browser (e.g., 1732).
    The Edit User page. The user's internal ID is displayed in the address bar.
  11. Click theicon in the top bar > Swagger Docs in the Tools section.
  12. Enter the keyword user in the search text box, then click User from the results to open the Swagger interface in a new tab.
    The Swagger API Documentation page.
  13. Scroll down to view the user resource.
  14. Click GET /user/users/me (who am I?) to expand it.
    The GET /user/users/me endpoint.
  15. Click Try it out!
  16. Record or copy the id number from the currentOrg section to your clipboard. This is the current org's internal ID.
    The Response Body section of the GET /user/users/me endpoint.
  17. Scroll up and expand the org resource to display the available endpoints.
  18. Click GET /user/org/{orgId}/user/{userId} (load a user org membership) endpoint to expand it.
    The GET /user/org/{orgId}/user/{userId} endpoint.
  19. Enter the org number copied during step 16 in the orgId field.
  20. Enter the user ID, copied during step 10 from the Edit User page, in the userId field.
    The expanded GET /user/org/{orgId}/user{userId} endpoint.
  21. Click Try it out!
  22. From the Response Body, record or copy the id number to your clipboard. This is the user's org membership ID number.
    The Response Body section of the GET /user/org/{orgId}/user/{userId} endpoint.
  23. Scroll up and expand the apiKey resource to display the available endpoints.
  24. Click POST /user/apiKey (create an api key) endpoint to expand it.
    The POST /user/apiKey (create an api key) endpoint.
  25. In the Parameters section, click the Example Value box to populate the template in the body text box.
    The Example Value box.
  26. In the body text box, delete the 0 in the orgUserId attribute, then enter the user's org membership ID number, obtained in step 22. 
  27. Enter a descriptive name for the API key in the name attribute (e.g., Integration Account).A completed body text box.
    The canImpersonate attribute makes it possible to impersonate another user while using the API key; however, only super admins can enable impersonation through the API. If you're not a super admin, setting this attribute to true will result in an error. Contact Resolver Support should you wish to enable this feature. For more information on impersonating a user with an API key, see the Impersonation section of the Use an API Key article.
  28. Click Try it out!
  29. Copy the apiKey from the Response Body and store it for safekeeping. 
    The Response Body displaying the ID and API key.
    For security purposes, once an API key is generated, it cannot be retrieved. If you misplace an API key, a new key must be generated.

See the Use an API Key or Delete an API Key article for additional instructions.

Use an API Key to Make Calls

See the following articles for additional information on API keys:

Impersonation

API keys can be used to authenticate requests in Core while impersonating another non-admin user; however, note the following:

  • Impersonation can only be enabled by a super admin at the time the key was created. Should you wish to enable impersonation, contact Resolver Support to create a new API key.
  • Any non-admin user can be impersonated, provided you've obtained their user ID and the user is active in the org the API key was created for.
  • Actions performed while impersonating using an API key are captured in the audit trail as "[API User's Name] impersonating [Impersonated User's Name]". 
  • If a user is impersonated using an external system (integration), the Modified By property on an object will show "[API User's Name]", but would still be captured in the audit trail as "[API User's Name] impersonating [Impersonated User's Name]".

To impersonate a user with an API key, open a supported endpoint in Swagger, enter the API key in the x-api-key field and the ID of the user to be impersonated in the impersonate-user-id field. The user ID can be obtained from the address bar of your browser after navigating to the Edit User page for the user (e.g., 1732).

The Edit User page. The user ID is displayed in the address bar.

Instructions

To use an API key in the Swagger interface:

  1. Navigate to the Swagger interface directly at https://YOUR_ENVIRONMENT.resolver.com/api? or log in as an admin and select the appropriate org, if required.
  2. Click theicon in the top bar > Swagger Docs in the Tools section.
  3. Click resource from the list to open the Swagger interface in a new tab.
  4. Expand a supported endpoint.
  5. Enter the API key in the x-api-key field to authenticate the call.
  6. Optional: If impersonation is enabled, enter the ID of the user who will be impersonated. Impersonation can only be enabled by a super admin. See the Impersonation section below for more details.
    The POST /data/file/file endpoint in the file service.
  7. Complete the remainder of the fields as required.

Example

curl -X POST --header 'Content-Type: multipart/form-data' --header 'Accept: application/json' --header 'x-api-key: YOUR_API_KEY' --header 'impersonate-user-id: IMPERSONATED_USER_ID' 'https://YOUR_ENVIRONMENT.resolver.com/data/file/file'

Delete an API Key

To delete an API key:

  1. Log in as an admin and select the appropriate org, if required.
  2. Click theicon in the top bar > Swagger Docs in the Tools section.
  3. Click any resource to open the Swagger interface in a new tab.
  4. Click the apiKey service to display its endpoints.
  5. Click GET /user/apiKey/{id} (retrieve an api key by id) to expand it.The apiKey service.
  6. Enter the user ID of the account the API key was created under in the id field. The user ID can be obtained from the address bar of your browser after navigating to the Edit User page for the user.The GET /user/apiKey/{id} (retrieve an api key by id) endpoint.
  7. Click Try it out!
  8. Copy the id from the Response Body to your clipboard. This is the internal ID for the API key.The id in the Response Body.
  9. Click DELETE /user/apiKey/{id} (delete an api key) to expand it.
  10. Paste the internal API key ID obtained from step 8 above in the id field.The DELETE /user/apiKey/{id} (delete an api key) endpoint.
  11. Click Try it out! to delete the API key.

Session Token Overview

Session tokens can be created by any active users of the org by logging in and creating a JSON bearer token, which is valid for 15 minutes.

Important Notes

  • These tokens are tied to the user's org account. This means that if a user doesn't have permission to perform an action in Core, they won't be able to do it through the API.
  • Session tokens are valid for 15 minutes. To extend the session, the token must be refreshed before it expires. Tools that perform long operations may require a child thread to guarantee the refresh window is not missed.
  • Users must have a valid password. Because passwords expire based on the org's password policy, this method is not recommended for static integrations.
  • When logging in via SSO, if a user is not already authenticated by their IdP (e.g., logged in through their corporate network), the login process depends on the IdP and may need to be customized. For example, on ADFS and Azure, users outside the corporate network are generally redirected to a login web page. In this case, the integration must be customized to handle credential submission through the page as well as receiving and passing the IdP's response back to Core.

The /user/authenticate call to create a session token.

See the Create & Renew a Session Token for more information.

Create & Renew a Session Token

Session tokens are valid for 15 minutes after logging in and creating the JSON bearer token. Tokens must renewed before the 15-minute expiry window ends. See the Session Token Overview article for important notes.

What's the best way to get the org ID? For regular end users, should we tell them to get it from their admin? I would say run the handy "who am I" call (see step 14 of Create an API Key)

Create a Session Token

To create a session token:

  1. Navigate to https://YOUR_ENVIRONMENT.resolver.com/api?.
  2. Scroll down to the authenticate endpoint.
  3. Click POST /user/authenticate.
  4. Click the Example Value box to populate the template in the body text box, then enter your login credentials and the org ID in the request body.
  5. Click Try it out! to return one of the following responses:
    • 401 Unauthorized: The login credentials are incorrect.
    • 404 Not Found: The user is not an active member of any orgs.
    • 200 Success: The user was successfully authenticated.
  6. If successful, copy the bearer token to your clipboard. This token is valid for 15 minutes and must be entered in the authorization header of each request.

Renew a Session Token

To maintain the current session:

  1. From Swagger, scroll down to the authenticate endpoint.
  2. Click GET /user/authenticate (Renew token).
  3. Enter the bearer token that's about to expire in the authorization header.
  4. Click Try it out! to return a new token, which is valid for 15 minutes.
  5. Copy the new token to your clipboard and use it for any subsequent calls.