Use the Postman collection

The SecureAuth Identity Store Postman collection is a convenient way to use the Identity Store API. Built-in environment variables help to set up the API environment so you can start using the API quickly, without the UI.

Using the Postman collection is not a requirement. If you want to work in your own development environment, you must Obtain credentials to create an access token. This works differently outside of Postman so be sure to follow the previous link rather than the following instructions.

Download and import the Postman collection

These instructions explain how to set up the Identity Store API Postman collection.

If you already have Postman, open it so you can Import the Identity Store API collection and skip to step 3.

  1. Install the latest Postman application.

  2. Start Postman. (It might start automatically after installation. If not, look for an orange icon on your desktop.)

  3. Check with your administrator to ensure you have the following:

    1. Name of the identity store you will work in. The default identity store ID is default. (You'll use the name later in these steps to set the ids_id variable.)

    2. At least developer privilege in the identity store you will access. (You must have this privilege to obtain credentials.)

      You need developer privileges to execute APIs, and you need privileges for the objects you will modify through the API.  For example, you need group privilege to modify groups in general or dynamic group privilege to modify a specific group.

    3. Your username and password for the identity store you will obtain your credentials from. (These are needed to obtain the client ID and client secret.)

  4. Download the Identity Store API zip file, secureauth_ids_api_v1.0.zip, available on the SecureAuth Product Downloads page. Extract the two Postman JSON files to any directory you'd like.

  5. Import the Postman collection and environment variables, called SecureAuth IDS API v1.0.postman_collection.json and SecureAuth IDS API v1.0.postman_environment.json.

    postman_import.png

Set global environment variables

A global environment variable represents a value that you can use over and over in requests. Variables are useful because if you need to change the variable for any reason, you change it once, and every request that uses the variable is changed automatically.

To see the SecureAuth IDS API v1.0 environment variables file in Postman, click the Environments tab on the left side and then under Globals, select SecureAuth IDS API v1.0. Notice the different default variables for your use. You can also create your own, but these will get you started.

postman_env_vars.png

In Postman, variable names are surrounded by double curly braces, {{ }}; for example, {{tenant}}. Environment variables are in the endpoint URLs and in Header areas. The following image shows variables in an endpoint URL, wrapped in curly braces, highlighted by red boxes:

variables_curly_braces_ex.png
  1. Set the environment to use the SecureAuth IDS API v1.0 environment.

    environ_set.png
  2. Set the tenant variable.

    The tenant variable maps to the URL where your SecureAuth Identity Store is located.

    Example: acme.ids.secureauth.com

  3. Set the ids_id variable.

    This variable is set to the default Identity Store, called default. You can change the Identity Store variable when you need to work in a different identity store. (All identity store IDs other than default will be unique strings that look like this: c51e0fce-e856-49fd-a68f-5a37e5cf22b8.)

    Example: default

  4. Set any other variables that will help you avoid repetitive typing or cutting and pasting.

    Example: If you need to perform multiple requests for a different user, get the user's ID and then set it as the Current Value for the user_id variable. Each request you make that requires a user_id will automatically use the variable you set.

Obtain API credentials in Postman

The following steps show how to get the client ID and client secret so you can obtain an access token. You need an access token to use the Identity Store API.

If you are working in your own development environment, not in Postman, see Obtain credentials.

  1. Obtain your client ID and client secret from the Identity Store UI.

    1. Open the Identity Store. In a browser, enter a link from your administrator or in the SecureAuth® Identity Platform, on the left side of the page, click Identity Stores.

    2. Open your profile to get your client ID and client secret.

      profile_open_api_creds.png
    3. Copy your API credentials to a safe location, which is useful if you don't want to open the UI when you need them. (If you misplace your credentials, you can generate them again from here. Whenever you generate new credentials, you must request a new access token.)

      api_creds_copy.png
    4. Set your credentials in Postman. Open the Environments tab and select SecureAuth IDS API v1.0.

      Copy the ID and set it as the client_id variable in Postman.

      Copy the Secret and set it as the client_secret variable in Postman.

      Save the changes you made in the Environments tab.

  2. Generate an access token.

    Warning

    Do not share your client ID, client secret, or access token values. This is especially important if you decide to share your Postman collection. Be sure to keep your API credentials private and secure.

    access_token_fresh.png
    1. Open the Collections tab and select SecureAuth IDS API v1.0.

    2. In the Credentials folder, select GET Get Access Token.

    3. On the right side of the page, select the Auth tab and be sure it's set to Basic Auth. Notice that Username and the obscured password is set to the client_id variable, which will use the one you set.

    4. Send the request.

      The token variable is set automatically based on the JavaScript in the Postman definition.

Send a request

Now that you have imported the SecureAuth Identity Store collection and customized the default variables, send a request to be sure everything is working right.

  1. If it has been over an hour since you obtained an access token, refresh the token.

    Open the Credentials folder, select GET Get Access Token, and send the request.

  2. In the Collections tab, expand the SecureAuth IDS API v1.0 collection and open the Users folder.

  3. Select GET Me and send the request.

    You should receive a 200 OK status in the upper right of the Body response window, and see your set attributes in the body.

    If you receive an error status, try the following:

    • Check the values in your environment variables.

      Open the Environments tab, select the SecureAuth IDS API v1.0 collection, and be sure that tenant, ids_id, client_id, client_secret, and token are set correctly.

      If not set, set them now and be sure to save your changes.

      env_vars_set_example.png
    • Be sure that the access token has not expired. If the token has expired, you'll see an error message: Access token is invalid

      If the access token is the problem, see step 1 above, then send the GET Me request again.

    • If you've sent the request to the right ids_id, confirm with your admin that you are a user in that identity store.

  4. You can now work in the Identity Store.

    Read about the SecureAuth Identity Store API requests and parameters.