Official: IdentityNow Postman Workspace

jordan_violet · October 10, 2022, 12:39pm

Update: This guide can now be found in the API docs here: Postman Collections | SailPoint Developer Community

IdentityNow Postman Workspace

Here you will find the official Postman Workspace for IdentityNow APIs. If you have any questions, comments, suggestions, or issues with this workspace or any collections within, let us know here.

Getting Started

You will forever find the IdentityNow workspace here: IdentityNow Postman workspace

You can also click these buttons if you just want a single collection

API	Postman Collection
V3 API
Beta API
V2 API
cc/private API
SaaS Connectivity

When you navigate this link, you’ll see our workspace, and you’ll find the collections of APIs on the left-hand side. Read the following guide to learn how to use them:

Fork the Collection

Hover over the collection you’d like to fork, click the ellipse on right-hand side, and click ‘Create a fork’.

Choose a label for your forked collection, choose the workspace that you’d like to fork it into (usually “My Workspace,” unless you know what you’re doing), and ensure that ‘Watch original collection’ is checked.

Click the ‘Fork Collection’ button.

Create A Postman Environment

To make things easier for you when using Postman, we’ve built our official workspaces around usage of Postman’s environments feature. With our latest update, we’ve added an environment to the postman workspace which you can fork in the same manner that you did the collection. This will allow you to get updates to the environment in the future as we continue to add new capabilities to our workspace. In case you decide to use your own, these fixes/improvements mean you’ll need to update your environments. You will need the following environment variables in your Postman environment:

Environment Variable	Required	Description
tenant	*	This is your IdentityNow tenant, typically your company’s name.
clientId	*	This is the client ID for the API client or personal access token.
clientSecret	*	This is the client secret for the API client or personal access token.
domain		This field is optional and is only needed for a select few who may have a domain in their API URL that differs from “identitynow”.

Getting Collection Updates

This is the big one, right? What about when the APIs get updated? Thankfully, Postman has a feature built-in for this, and it ties back to your ensuring that the ‘Watch original collection’ option is checked.

All you have to do now to check for updates is this - in your own personal workspace where you forked the collection, do the following:

Hover over the collection, click the ellipse on the right-hand side, and click ‘Pull changes.’

If there are no new changes, then you are up to date. If there are new changes, it will look like the following image. Just click the Pull Changes button, and that’s it!

Collection Features

In addition to managing the collections for you, we’ll continue to add features as they’re requested and we can get to them. Got a collection/workspace level request? Let us know here!

To boot, we’ve added a collection feature to V3 APIs originally posted by @Rich_Miller on automating JWT creation and improved by @atarodia to automatically retrieve the token when it expires. Thanks to Richard and Animesh for their contributions!

jordan_violet · October 10, 2022, 12:41pm

LukeHagar · October 10, 2022, 12:59pm

Hey @jordan_violet,

I just wanted to provide some initial observations,

The below endpoints seem to be missing from their respective collections.
I’m happy to help gather details on them if needed.

CC:

/cc/api/user/get
/cc/api/system/getStatus

V2:

/v2/dashboard

I’ll keep an eye out for more like this as I use the collection

jordan_violet · October 10, 2022, 1:12pm

@LukeHagar, please! If you can send me all of the call details, or even a sample collection with those calls in them, I can get them added to the SailPoint collections.

edmarks · October 10, 2022, 2:03pm

Regarding the “BETA” API’s

Will a collection be added for these also?
Any plans for communications regarding API’s moving from “BETA” to “V3”?

jordan_violet · October 10, 2022, 2:22pm

Great question! I can’t believe I missed the Beta APIs! They’re added now

As for communication APIs moving from Beta to V3, give us some time and we’ll have a process for that soon!

ghostclass · October 10, 2022, 7:48pm

One piece of feedback - it looks like the hierarchy for each endpoint has been removed in most cases.

I.e. Under v3/sources folder, the last API spec I imported had generic (not single) calls directly within, then subfolders for calls which required an ID. This made is really easy to determine which were the base calls for a given endpoint and which were sub calls of the end point. This was pretty handy in sources as it had a few levels of subfolders as you started looking at the schema/policy management sub-endpoints.

Can we re-instate the folder structure?

LukeHagar · October 10, 2022, 8:17pm

Hey @jordan_violet,

Here is what I have so far on those Endpoints (Not Complete):

GET /v2/dashboard

Response Shape:

export type dashboard = {
  access: any[];
  accessCount: number;
  accessProfileCount: number;
  accountCount: number;
  accounts: any[];
  appCount: number;
  attributes: any;
  created: string;
  displayName: string;
  email: string;
  entitlementCount: number;
  firstName: string;
  id: string;
  identityProfile: any;
  inactive: boolean;
  isManager: boolean;
  lastName: string;
  modified: string;
  name: string;
  owns: any;
  ownsCount: number;
  protected: boolean;
  roleCount: number;
  source: any;
  status: string;
  synced: string;
  tags: any[];
  tagsCount: number;
  visibleSegmentCount: number;
};

GET /cc/api/user/get

Response Shape:

export type userResponse = {
  alias: string;
  altAuthVia: string;
  altAuthViaIntegrationData: null;
  attributes: { lastLoginTimestamp: number; uid: string; firstname: string };
  auth: { service: string; encryption: string };
  bxInstallPrompted: boolean;
  disablePasswordReset: boolean;
  displayName: string;
  email: string;
  employeeNumber: null;
  enabled: true;
  encryptionCheck: null;
  encryptionKey: null;
  externalId: string;
  feature: string[];
  featureFlags: any;
  federatedLogin: boolean;
  id: string;
  kbaAnswers: number;
  loginUrl: string;
  meta: any;
  name: string;
  onNetwork: boolean;
  onTrustedGeo: true;
  org: {
    actionButtonColor: string;
    activeLinkColor: string;
    adminStrongAuthRequired: boolean;
    authErrorText: null;
    brandName: string;
    countryCodes: null;
    emailFromAddress: string;
    emailTestAddress: string;
    emailTestMode: boolean;
    enableAutomaticPasswordReplay: boolean;
    enableAutomationGeneration: boolean;
    enableExternalPasswordChange: boolean;
    enablePasswordReplay: boolean;
    integrations: any;
    kbaReqAnswers: number;
    kbaReqForAuthn: number;
    lockoutAttemptThreshold: number;
    lockoutTimeMinutes: number;
    logo: null;
    maxClusterDebugHours: string;
    maxRegisteredUsers: number;
    mode: string;
    name: string;
    narrowLogoUrl: null;
    navigationColor: string;
    netmasks: null;
    notifyAuthenticationSettingChange: boolean;
    numQuestions: number;
    orgType: string;
    passwordReplayState: string;
    pod: string;
    productName: string;
    pwdResetDuo: boolean;
    pwdResetEmail: boolean;
    pwdResetKba: boolean;
    pwdResetPersonalEmail: boolean;
    pwdResetPersonalPhone: boolean;
    pwdResetPhoneMask: boolean;
    scriptName: string;
    standardLogoUrl: null;
    status: string;
    strongAuthKba: boolean;
    strongAuthPersonalEmail: boolean;
    strongAuthPersonalPhone: boolean;
    systemNotificationConfig: string;
    usageCertRequired: boolean;
    usernameEmptyText: null;
    usernameLabel: null;
    whiteList: boolean;
  };
  orgEncryptionKey: string;
  orgEncryptionKeyId: string;
  passwordResetSinceLastLogin: boolean;
  pending: boolean;
  personalEmail: null;
  phone: null;
  ptaSourceId: null;
  riskScore: 0;
  role: string[];
  status: string;
  stepUpAuth: boolean;
  supportsPasswordPush: boolean;
  uid: string;
  usageCertAttested: null;
  userFlags: any;
  uuid: string;
};

There ARE some incorrect types here, mainly the null ones, a couple of any types as well, I don’t have perfect examples to pull from

jordan_violet · October 10, 2022, 11:31pm

Do you have an old collection or screenshot you could DM me so I could see this visually?

jordan_violet · October 10, 2022, 11:38pm

@LukeHagar do you know if those would go in their own folders, ‘Dashboard’ and ‘Users’, respectively, or if they’d fall under an existing folder/tag?

ghostclass · October 10, 2022, 11:54pm

image312×1010 44.6 KB

jordan_violet · October 11, 2022, 12:03am

Ah, interesting, that is a collection by OpenAPI paths instead of OpenAPI tags. It would be possible for us to do that, but I know most people are used to folders by tags.

I’m going to see if we can generate multiple collections, so we can do them by both path and tag.

edmarks · October 12, 2022, 8:22pm

I just noticed a spelling difference for the “cc” collection where it’s “Identity Now cc (private) APIs” vs. “IdentityNow …”

jordan_violet · October 13, 2022, 1:00pm

Good catch @edmarks–fixed

jordan_violet · October 14, 2022, 12:46am

@christina_gagnon brought to my attention that some of the requests throughout the V3 and Beta collections had Oauth 2.0 instead of inherit from parent. I fixed that, and now all requests are set to inherit from parent.

You’ll get these changes whenever you pull the latest changes

atarodia · October 14, 2022, 8:25am

Hey @jordan_violet,

In V2 API Collection under Access Profiles and Apps, some of the End Point has {{name}} which makes it unusable for Vanity URLs. Can you please change it to {{api-url}}.

jordan_violet · October 14, 2022, 12:05pm

@atarodia thanks for looking out. I actually changed it to {{baseUrl}} and inserted {{tenant}} and {{baseUrl}} as collection variables, just like V3 and Beta collections have, that way there is some consistency.

whoiscjay · November 22, 2022, 6:23am

Hey @jordan_violet - this is fantastic!! Have transitioned over this week!

One additional private API that seems to be missing is an API list all of the cloud rules from the tenant:

CC:
GET /cc/api/rule/list

I use this to verify the rules are imported into each tenant (once unescaped)

Thanks
Chris

jordan_violet · November 22, 2022, 6:29am

@whoiscjay I’m glad to see you’re using the official collection!

Thanks for helping us improve the cc API collection. The endpoint you mentioned has now been added to the collection. If you have any information on the request body, headers, etc. I’ll add them as well.

justinrhaines · December 1, 2022, 5:35pm

I noticed on the V3 and Beta collections that the {{tenant}} value is blank or has “sailpoint”, respectively. Would it be possible to change the default value of that field to “{{name}}”?