Authentication
How to authenticate API calls to SailPoint.
API calls authenticate with OAuth: obtain an access token, then send it as an Authorization bearer header on every request.
- Obtain a token via OAuth
- Send Authorization: Bearer <token>
- Tokens expire and must be refreshed
- Use least-privilege scopes
Authenticating API calls to SailPoint means obtaining an OAuth access token and sending it as a bearer header on every request. Without a valid token the API rejects the call; with one, the token’s scopes determine what the call may do. This page covers the practical mechanics.
The basic pattern
- 1. Obtain a token from the OAuth token endpoint using client credentials.
- 2. Send it on each request:
Authorization: Bearer <token>. - 3. Refresh when it nears expiry; re-authenticate on
401.
# 1. get token, then 2. call with it
curl -H "Authorization: Bearer $TOKEN" \
"https://tenant.api.identitynow.com/v3/accounts?limit=50"What happens without a token
A missing or invalid token returns 401 Unauthorized. A valid token with insufficient scope returns 403 Forbidden. Distinguishing the two is the first step in debugging access problems: 401 means "who are you?", 403 means "you may not do that".
Token lifecycle in code
Robust clients acquire a token once, cache it, and transparently refresh it shortly before expiry, retrying a single time on an unexpected 401. Hard-coding a token or fetching a fresh one on every call are both anti-patterns, the former breaks on rotation, the latter wastes calls and invites rate limiting.
Common pitfalls
- Confusing 401 and 403, wasting time on the wrong cause.
- No refresh handling, so long-running jobs fail when the token expires.
- Credentials in source control.