Quickstart

A shareable guide for integrating with the Esperto Assessments Platform. The examples use the Growth Institute instance https://scalinguptoolkit.com — swap in your own instance domain.

Three things to know up front

1. Token endpoint. Not /oauth/token. The flow uses two endpoints:

• Authorization: https://scalinguptoolkit.com/api/v1/auth/authorize
• Access token: https://scalinguptoolkit.com/api/v1/auth/access_token

2. Grant type. Use Authorization Code for interactive/browser setups, or Client Credentials for headless server-to-server clients. OAuth2 is required for any write interaction. (API Key and Basic auth exist but are read-only.)

3. Credential placement. Send client_id and client_secret in the request body (not as a Basic Auth header). The issued access token is then sent as a Bearer token in the Authorization header on every API call.

There is a callback (return) URL where the token is delivered for the Authorization Code flow. Esperto sets this on their side — send Esperto the return URL you want to use so it can be registered on your client. Without it the interactive flow can't complete. (The Client Credentials flow needs no callback.)

Base URL

https://scalinguptoolkit.com/api/v1

Authentication flow (2 steps)

Step 1 — Get a token
  → POST https://scalinguptoolkit.com/api/v1/auth/access_token
    Content-Type: application/x-www-form-urlencoded
    body: grant_type=client_credentials
          client_id=<client_id>
          client_secret=<client_secret>
          scope=members groups
  ← JSend response; bearer token sits inside `data`

Step 2 — Call the API
  → GET https://scalinguptoolkit.com/api/v1/members
    header: Authorization: Bearer <access_token>

See Authentication for the full detail on both grant types.

First calls to test

# List all members
GET  /api/v1/members
Authorization: Bearer <access_token>

# Get one member
GET  /api/v1/members/{memberid}
Authorization: Bearer <access_token>

# List all groups (folders)
GET  /api/v1/groups
Authorization: Bearer <access_token>

# List members in a group
GET  /api/v1/groups/{groupid}/members
Authorization: Bearer <access_token>

Notes

• Scopes must match. The scopes you request at authorization must match what Esperto has enabled on your client. Requests outside your enabled scopes are rejected. See API Access Setup.
• Postman: the Authorization Code setup works with Grant Type Authorization Code, Auth URL api/v1/auth/authorize, Access Token URL /api/v1/auth/access_token, and "Add token to header" as a Bearer token.
• Read status, not the HTTP code. Every call returns HTTP 200; success is in the JSend status field. See Authentication.
• The client secret is shown only once. Store it safely — it can't be retrieved later. If lost, Esperto generates a new one.

Checklist to go live

1. Send Esperto your callback (return) URL so it can be registered (for the Authorization Code flow).
2. Configure OAuth2 with the URLs above.
3. Authenticate and confirm you receive a Bearer token.
4. Test GET /members and GET /groups.
5. Tell Esperto if you need additional endpoints (e.g. Campaigns or Reports).

Questions? Contact us.