A simple guide to connect your system to SprintSuite. SprintSuite uses a standard, secure method called OAuth 2.0 — think of it as getting a temporary visitor pass that lets your software talk to ours.
You trade a permanent username/password for a short-lived pass, and use the pass on every request.
What we'll give you
Before you start, SprintSuite provides four things:
You get | Think of it as | Example |
Web address (base URL) | Where to send requests | |
Client ID | A username for your app | abc123… |
Client Secret | A password for your app — keep it secret | xyz789… |
Permissions (scopes) | What you're allowed to see/do | read_staff , read_jobs |
The big picture — 3 steps
1. Get a pass — swap your Client ID + Secret for an access token.
2. Use the pass — send that token with every API request.
3. Renew the pass — tokens expire (~2 hours); get a fresh one automatically.
Step 1 — Get an access token (your pass)
Send one request to the token endpoint:
curl -X POST "https://your-company.sprintsuite.com.au/oauth/token" \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "scope=read_staff read_jobs"
You get back:
{
"access_token": "the-pass-abc123", ← your temporary pass
"token_type": "Bearer",
"expires_in": 7200, ← seconds until it expires (7200 = 2 hours)
"refresh_token": "renew-key-def456", ← (if provided) use this to renew — see Step 3
"scope": "read_staff read_jobs"
}Save the "access_token" (and the "refresh_token" if you have one).
Step 2 — Call the API (show your pass)
Add the token to the Authorization header on every request — that header is your pass:
curl "https://your-company.sprintsuite.com.au/api/v1/staff" \
-H "Authorization: Bearer the-pass-abc123"
If the pass is valid and has the right permission, you get your data back. Reuse the same token for as many calls as you like until it expires — don't fetch a new one per request.
Step 3 — Renew the token (when it's about to expire)
A pass lasts about 2 hours (trust the "expires_in" value, not this number). When it's nearly up, get a new one - you will not need to contact us for this.
If you received a "refresh_token" - you should use it (fastest)
curl -X POST "https://your-company.sprintsuite.com.au/oauth/token" \
-d "grant_type=refresh_token" \
-d "refresh_token=renew-key-def456" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"
You'll get a brand new "access_token" (and usually a new "refresh_token" too). Save both as the old one will stop working.
If you did not receive a "refresh_token": just repeat Step 1 to get a fresh pass.
Note: Don't wait for it to break. Either renew a few minutes before "expires_in" runs out, or renew automatically the moment you get a '401 Unauthorized', then retry the request once.
Quick do's & don'ts
✅ Keep the Client Secret and tokens private — never in public code, URLs, screenshots, or emails.
✅ Reuse one access token across many calls until it expires.
✅ Ask only for the scopes you actually need.
❌ Don't hard-code a token — they expire. Store the Client ID/Secret and fetch tokens as needed.
❌ Don't request a new token on every single call — you'll hit limits and slow yourself down.
If something goes wrong
You see | It means | Do this |
401 Unauthorized | Pass missing / expired / wrong | Get a new token (Step 3), then retry |
403 Forbidden | Valid pass, but no permission for that action | Ask us to add the scope |
Token request fails (400) | Client ID/Secret wrong, or a typo in "grant_type" / "scope" | Double-check your details |