Authenticating to the SailPoint API Gateway
Key Takeaways
The client first obtains a bearer access token from the token endpoint. It sends that token to the protected resource.
A SailPoint personal access token provides user-associated client credentials. An API key can act without a user context for supported operations.
Check the API operation’s supported flow, scope, user level, and resource restrictions.
A valid bearer token can receive 403 when the caller lacks required permission or user context.
Locate each component
An application programming interface (API) gateway provides an entry point for calls to services. It can route an authenticated call and enforce controls such as access and throttling. In a SailPoint integration, distinguish the calling application, the OAuth 2.0 client configuration, authorization server, token endpoint, and protected resource operation. The client’s successful token request and the resource’s authorization decision are separate events. Use the API documentation for the endpoint version and tenant environment.
| Component | What to inspect |
|---|---|
| Calling client | Intended action, approved identity context and secure credential storage |
| OAuth client registration | Enabled client and supported grant types, plus registered redirect rules for browser flows |
| Token endpoint | Correct tenant and grant exchange, and only the credentials needed for that exchange |
| Protected resource at API entry | Supported method and route, bearer access token, allowed scopes and any required user context |
| Back-end operation evidence | Response, affected resource and documented follow-up for accepted work |
In the usual documented tenant hostname pattern, the token request is sent to https://{tenant}.api.identitynow.com/oauth/token. Confirm your environment’s published endpoint. Supply the credentials through a supported protected request. Keep secrets out of URLs, logs and screenshots in operational use. The token response contains an access token. Send the access token using Authorization: Bearer {access_token} on the protected request. A client secret belongs to the exchange with the authorization server. Do not substitute it for the access token.
Select the credential and flow for the task
For system-to-system use, SailPoint documents the client credentials grant. A platform API key identifies a client independent of any individual user. A personal access token (PAT) provides its own client ID and secret and is associated with a user. SailPoint’s PAT flow uses those credentials to obtain an access token through client credentials. The resulting authorization can depend on that user’s permissions, the scopes and the endpoint requirements. An endpoint requiring a user context may reject a token obtained with a general API key. Choose an approved credential that satisfies the endpoint’s actual requirement. For example, the product docs warn that some API keys can fail when searching identities, roles or entitlements in a tenant with Data Segmentation enabled. The equivalent user-associated path can enforce individual record visibility. Keep that scope check when choosing a replacement credential.
For an interactive delegated integration, the authorization code flow can have the user complete an authorization step and return a code to the registered redirect. The application then exchanges the code for tokens. Proof Key for Code Exchange (PKCE) protects against intercepted or injected codes when correctly used. The OAuth security best current practice requires it for public clients and recommends it for confidential clients. Use the provider’s matching client configuration rather than applying the same flow to every program. Keep ID tokens used for an OpenID Connect sign-in separate from API access tokens.
Work a 403 on a user-context endpoint
Suppose a scheduled integration obtained a valid token using a general client API key. A service-to-service read works, but a second endpoint explicitly requires a user level and rejects that call. Review the endpoint’s Authorization details, including grant flow and any required scope. If the task is authorized and this endpoint requires a user when called with the chosen flow, create or use an approved user-associated credential with the appropriate user level and narrowly scoped permissions. A token reissued from the same userless key can leave the requirement unsatisfied. Increasing scope cannot create a missing user context or change a PAT holder’s underlying platform privileges.
When a resource returns 401, first check bearer header and token validity, expiration and host. For 403, check the endpoint’s scope, authorization context and permitted resource. Log the redacted route, status, correlation identifier if available, and the test identity’s permissions. Demonstrate a required allowed call and a scoped denied call. A new integration can also test an expired token in the sandbox to verify its credential-refresh error path separately. Record the actual request/result rather than relying on token issuance as proof that either attempt performed the requested operation.
See SailPoint’s authentication flow, credential scopes and user levels, API key and PAT configuration, and the OAuth security best current practice.
An approved endpoint requires a calling user level. A system obtains a valid token using a SailPoint API key with no user association, and the call returns 403. What should the team verify?
Whether a longer token lifetime implicitly adds a user
Whether the endpoint’s permitted flow supports an approved user-associated credential with the required level and scope
Whether sending the client secret as the bearer token grants user rights
Whether retrying a read requests the missing role from the identity profile
An operator creates SailPoint PAT credentials. What is placed in the Authorization header of a resource API call?
The bearer access token returned after exchanging the client ID and secret with the token endpoint
The raw secret shown at PAT creation
The signed SAML service provider metadata
The password of the account that created the PAT
Sections you finish are checked off in the contents.