Authentication

Overview

NERM supports two authentication methods to allow customers to authenticate to NERM API endpoints:

1. NERM API Key (Legacy) - NERM-specific bearer tokens
2. SailPoint Human Fabric (SHF) API Token (Recommended) - OAuth 2.0 JWT access tokens from SHF

Both authentication methods use bearer tokens in the request header.

Authentication Methods

NERM API Key

NERM API Key Authentication

Deprecated

Legacy NERM API keys are deprecated and do not support scopes. Use SailPoint Human Fabric (SHF) API tokens instead. For details on the scopes available with SHF API tokens, refer to Authorization.

NERM-specific bearer tokens can be generated by following the instructions here.

Example

To use your NERM bearer token, provide it in the header with the request:

curl --location 'https://mycompany.nonemployee.com/api/v1/non-employee-sources' \
--header 'Authorization: Bearer {nerm_token}'

SHF API Token

SHF API Token Authentication

NERM now supports authentication using SailPoint Human Fabric (SHF) personal access tokens. This allows you to use the same authentication method across both SHF and NERM APIs.

Generate a Personal Access Token

A personal access token (PAT) is a method of authenticating to an API as a user without providing a username and password. Any SHF user can generate a PAT by following these steps:

1. Select Preferences from the drop-down menu under your username, then Personal Access Tokens on the left. You can also go directly to the page by using this URL (replace [tenant] with your SailPoint Human Fabric tenant): https://[tenant].identitynow.com/ui/d/user-preferences/personal-access-tokens

2. Click New Token and enter a meaningful description to help differentiate the token from others.

caution

The New Token button will be disabled when you reach the limit of 10 personal access tokens per user. To avoid reaching this limit, it is recommended that you delete any tokens that are no longer necessary.

3. Click Create Token to generate and view the two components that comprise the token: the Client ID and the Client Secret.

Important

After you create the token, the value of the Client ID will be visible in the Personal Access Tokens list, but the corresponding Secret will not be visible after you close the window. Store the Secret somewhere secure.

4. Copy both values somewhere that will be secure and accessible to you when you need to use the token.

Request Access Token

Once you have created the PAT, use the client credentials grant flow to obtain a JWT access token:

curl --location 'https://[tenant].api.identitynow.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id={clientId}' \
--data-urlencode 'client_secret={clientSecret}'

The response will contain a JWT access token:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 749,
  "scope": "read write"
}

Use Access Token with NERM APIs

Include the JWT access token in your NERM API requests:

curl --location 'https://mycompany.nonemployee.com/api/v1/non-employee-sources' \
--header 'Authorization: Bearer {access_token}'

The JWT access_token grants access matching that of the user who generated the PAT. For example, if the user who generated the PAT is an admin, the returned JWT access_token would grant admin access to the NERM APIs.

Token Expiration

The expires_in value in the token response describes the lifetime, in seconds, of the access_token. For example, the value 749 means that the access_token will expire in approximately 12.5 minutes from the time the response was generated. When the token expires, you will need to request a new access token using your PAT.

More Information

For detailed information about SHF authentication methods, grant flows, and troubleshooting, refer to the SHF Authentication Guide.

For information about Non-Employee Risk Management authorization and scopes, refer to Authorization.

For information about how scopes work across SHF APIs, refer to the SHF Authorization Guide.