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. Identity Security Cloud (ISC) API Token (Recommended) - OAuth 2.0 JWT access tokens from ISC

Both authentication methods use bearer tokens in the request header.

Authentication Methods

NERM API Key

NERM API Key Authentication

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}'

ISC API Token

ISC API Token Authentication

NERM now supports authentication using Identity Security Cloud (ISC) personal access tokens. This allows you to use the same authentication method across both ISC 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 ISC 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 Identity Security Cloud 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 ISC authentication methods, grant flows, and troubleshooting, refer to the ISC Authentication Guide.

For information about authorization and scopes, refer to the ISC Authorization Guide.