Identifying Tenant and API URLs
Key Takeaways
Use the tenant organization name and discovered OAuth endpoints, especially when the browser uses a custom domain.
The browser authorize endpoint, token endpoint, registered callback and resource API have different purposes.
Read the documented service path and version before migrating a legacy URL.
Use a narrow authorized read to prove the intended tenant and resource before testing a write.
Choose the host by the job it serves
A single SailPoint tenant can have different hosts for the browser experience, OAuth authorization and the API. Identify the tenant and environment before copying any address. In the admin dashboard, use the organization name shown in the organization details. A registered branded domain can be the tenant's browser host while the SailPoint API and login host are still based on its SailPoint tenant name. Staging and production may have similar display names and distinct organization names, so check the actual values for the intended environment.
SailPoint documents tenant OAuth details at https://{tenant}.api.identitynow.com/oauth/info. Inspect the values labeled tenantName, cloudDomainUrl, authorizeEndpoint and tokenEndpoint. A discovery payload establishes the actual tenant endpoint values, including the browser portal and OAuth addresses, without guessing from one hostname. The examples below assume a fictional tenant called acme-stage. They illustrate vendor patterns and are not live integration targets.
| Purpose | Example address under documented SailPoint patterns |
|---|---|
| Open a default user-facing tenant portal | https://acme-stage.identitynow.com |
| Inspect server discovery for that tenant | https://acme-stage.api.identitynow.com/oauth/info |
| Start a browser authorization-code flow when discovery returns this authorizeEndpoint | https://acme-stage.login.sailpoint.com/oauth/authorize |
| Exchange authorized credentials or code for a token when discovery returns this tokenEndpoint | https://acme-stage.api.identitynow.com/oauth/token |
| Call a documented public identity listing resource | https://acme-stage.api.identitynow.com/public-identities/v1?limit=1 |
The authorization endpoint serves the browser step. The token endpoint serves the exchange. The application callback is the registered redirect URI that the client uses to receive the authorization result. It may be an address on an independently managed host. Check the redirect value in the OAuth client registration. Use the correct bearer token on the protected resource request and keep secret material out of URLs. Some official troubleshooting text gives a different authorize hostname. Prefer the tenant's discovered value, which is also the source recommended by SailPoint's OAuth setup section, and the current flow specification for the type of client you are using.
Match a path to the current operation
The host identifies the tenant and service surface. The operation documentation determines the valid path, method, version and query parameters. SailPoint's per-service API strategy uses a major version within the service path. For example, the current Getting Started and collection documentation show GET /public-identities/v1?limit=1 for a small resource response. The earlier shared version namespaces placed versions at the beginning of the path. SailPoint's migration table lists the earlier /v3/public-identities route among the legacy versions mapped to the current /public-identities/v1 service. The published transition retains legacy routes on a separate timeline. Verify both the particular endpoint and current lifecycle notices. A higher version can offer a different operation and contract. For example, the documented POST /public-identities/v2/search uses a structured search body and is marked experimental. It requires the endpoint’s specified opt-in header. Changing just the version and continuing to send the listing request would not perform that search. Keep experimental evaluations in the appropriate test environment.
For an integration moving between staging and production, obtain the intended tenant coordinates and use the applicable user or application registration for that tenant. Change the expected resource identifiers as needed. Before any write, test a narrow, authorized read against the official path and inspect the actual response. If the request returns a web login page, check whether an API call was accidentally routed to a user portal. If the tenant is right but the route does not resolve, compare the operation's documented path and version to what the client actually sent. An authenticated request can still use an incorrect path.
Work a migration from a branded portal
An employee signs in at https://identity.example.com. The staging discovery response says acme-stage and publishes the token address on acme-stage.api.identitynow.com. Use the discovered token endpoint for the exchange. Select the matching resource API host and endpoint specification for the approved read. A string replacement using identity.example.com as the API host assumes it serves a different product surface. Keep the browser portal, the client callback, and the two discovered OAuth endpoints in distinct configuration entries. This also makes it possible to check correctly when a login host or endpoint changes without requiring an unrelated routing change.
See the SailPoint tenant OAuth details, API specification, list request example, service version migration guide, and the experimental public identity search specification.
A branded staging portal is identity.example.com, and discovery returns a tokenEndpoint on acme-stage.api.identitynow.com. Where should the OAuth client exchange the authorized code?
At the published tokenEndpoint for acme-stage.
At the branded portal root.
At the discovered authorizeEndpoint, which serves the browser step.
At the callback configured to receive the browser result.
An authorized client is migrating the former V3 public identity listing to the current per-service version. Which documented resource request matches that goal on the correct API host?
GET /oauth/info/public-identities
GET /v1/public-identities
GET /public-identities/v1?limit=1
POST /oauth/token/public-identities
Sections you finish are checked off in the contents.