SCIM API Reference

Manage people in a workspace

SCIM is used by Single Sign-On (SSO) services and identity providers to manage people across a variety of tools. Our SCIM implementation targets version 2.0 of the protocol. You can find the RFC here.

Nova Credit supports member provisioning via helper apps with supported identity providers.

Note that SCIM actions cannot be undone. Please test your scripts thoroughly before executing them. Our customer support team is ready to assist you should you run into any trouble.

Accessing the SCIM API

The SCIM API is a proper REST API.

The base URL for all calls to the SCIM API is https://dashboard.novacredit.com/user/sso/scim. All SCIM methods are branches of this base URL.

Acquire a Bearer token

A bearer token for your organization is required to access the SCIM API.

To acquire a token:

Visit the Nova Credit Dashboard, and navigate to your SSO settings.
Make sure your SSO settings are properly configured, and that SCIM is enabled.
Visit the SCIM credentials page.
Your API url and bearer token should be available.

Use the token in a SCIM API request

The API token must be base64 encoded and included via an Authorization header with a type of Bearer when calling any of the SCIM methods.

Provide a JSON request body for POST, PUT, and PATCH write operations. Your HTTP Content-Type header can be application/json or application/scim+json.

A SCIM call may take a form like this:

 GET /Users HTTP/1.1
 Host: api.novacredit.com
 Accept: application/scim+json
 Authorization: Bearer ...

Installing the Nova Credit app in Microsoft Entra

In order to use the SCIM API via Microsoft Entra provisioning, you'll need to install the Nova Credit app and map the appropriate attributes (detailed below) in the Provisioning menu. More details can be found here.

If you are using Entra Groups for easier role management, you need to disable Provision Microsoft Entra ID Groups as these endpoints are not implemented.

Mapping roles

In order to ensure the proper format is sent to our API, you'll need to set up the roles mapping in a specific way in Entra. First, make sure you configure custom app roles for each role you intend to assign to your members. Make sure the Display name field matches the format described below. Once your app roles are created and assigned to your users, you should either map the roles.display attribute to the expression SingleAppRoleAssignment([appRoleAssignments]) for single-role users, or map the roles attribute to AppRoleAssignmentsComplex([appRoleAssignments]) for multiple-role users (i.e., if you have multiple child organizations and you want to assign a different role per organization to a user). More details on attribute mapping can be found here.

Active attribute

Installing the Nova Credit app in Okta

In order to use the SCIM API via Okta provisioning, you'll need to install the Nova Credit app and map the appropriate attributes (detailed below).

Scim settings

Unique identifier field for users userName (must be a user's email address)
Supported provisioning actions - push new users push profile updates
Authentication Mode - HTTP Header

Mapping roles

To ensure roles are appropriately assigned to users in Okta you need to create a custom attribute to either Users or Groups (if you plan on using Groups for easier role management).

Field	Value
`Data type`	string array
`Display name`	Roles (up to user)
`Variable name`	roles
`External name`	roles
`External namespace`	urn:ietf:params:scim:schemas:core:2.0:User
`Description`	(optional)
`Enum`	Enable Define enumerated list of values
`Attribute members`	Display name and value should be `CompanyName, PERMISSION`
`Attribute required`	Yes
`Attribute type`	Personal or Group
`Mutability`	READ_WRITE
`Attribute type`	Personal or Group
`Group Priority`	If attribute type is Group then Combine values across groups

Schemas

Nova Credit currently only supports the Core User schema (defined here).

Endpoints

Endpoint	Description
`GET /Users`	Returns a list of users. Note that deactivated users will not be retrieved by this endpoint
`GET /Users/:id`	Retrieves a single user
`POST /Users`	Creates a user
`PATCH /Users/:id`	Updates an existing user, overwriting specified values
`PUT /Users/:id`	Updates an existing user, overwriting all values
`DELETE /Users/:id`	Deactivates an existing user

User attributes

Attributes are the details associated with a user's account. These are the details that someone would typically see in their user account in the enterprise dashboard. The following table maps SCIM attributes to the profile fields that Nova Credit uses. Note that providing attribtues that are not supported will be ignored.

Nova Credit User Attribute	SCIM Attribute	Description
user_id*	id	The id of the user, as generated by Nova Credit
external_id	externalId	An external identifier you may choose to attach to the user for your own record-keeping
email*	userName	The email of the user. Note that providing anything in the "email" SCIM attribute will be ignored
first_name*	name.givenName	The first name of the user
last_name*	name.familyName	The last name of the user
customer_id*	roles	Which entity this user has permissions for. Format must be as follows: `"Company Name, ROLE"`, where `Company Name` is the name of the organization exactly as it is set up with Nova Credit, and `ROLE` is the role you would like to assign (see list of roles below). This field is case sensitive.
permission*	roles	The permissions the user has for your organization when accessing the Nova Credit Dashboard. See formatting rules above.
scim_active*	active	Whether or not the user is active or soft deleted.

* REQUIRED

Permissions

Below is a list of permissions that can be granted to users with a brief overview of the roles that may be assigned to users.

Nova Credit User Role	Available Actions	Access
ADMIN	Create and archive child accounts; Request, download, archive and request reports again; View consumer PII and report summary; Create and edit customer products; Access all team management (e.g. invite team members, remove team members, reset password); Customize branding; Access API explorer; Access production keys; Refresh webhooks	All data in both environments (production and sandbox)
PROTECTED_ADMIN	Archive child accounts but can create new accounts in sandbox only; Request report in all environment (but can only download, archive in sandbox); View consumer PII, report summary in sandbox only; Create and edit products; Access to protected team management only (e.g. invite, edit protected team members); Customize branding; Access API explorer; Access production keys; Refresh webhooks	All data in both environments (production and sandbox)
COLLABORATOR	View child accounts (but cannot add, remove or edit); Request, download, archive and request reports again but cannot export Activity page; View consumer PII and report summary; View team members (but cannot add, remove or invite)	All data except Developer, Products tab; Cannot switch between production and sandbox environment (access to production environment only after launch)
PROTECTED_COLLABORATOR	View child accounts (but cannot add, remove or edit); Request report in both environment but can download, archive and request reports again in sandbox only; View consumer PII and report summary in sandbox only; View team members (but cannot add, remove or invite)	All data except Developer, Products tab; Cannot switch between production and sandbox environment (access to production environment only after launch)
DEVELOPER	View child accounts (but cannot add, remove or edit); Request, download, archive and request reports again in sandbox only; Create products in sandbox only; Customize branding; access API explorer; Access production keys; Refresh webhooks in sandbox only	Accounts, Attributes, Developer, Products, Settings tab in both environment; Analytics, Countries, Team in sandbox only
PROTECTED_DEVELOPER	View child accounts (but cannot add, remove or edit); Request, download, archive and request reports again in sandbox only; Cannot switch between production and sandbox environment (access to production environment only after launch); Customize branding; Access API explorer; Access production keys; Refresh webhooks in sandbox only	Accounts, Settings tab in both environment; Analytics, Attributes, Countries, Developer, Products, Team in sandbox only
VIEWER	View data (but cannot edit)	All data except Developer, Products tab; Cannot switch between production and sandbox environment (access to production environment only after launch)

Permissions per organization

This SCIM implementation can accept multiple roles, each with their own displayName. If you have a standalone organization, users should only have a single role defined. Attempting to add multiple roles will result in errors or unexpected results. The Company Name portion of the displayName may be set to ALL if you have multiple child organizations, to grant permissions at the parent level, otherwise it must be formatted as specified in the above table.

Example

These example requests provide detailed examples of which attributes Nova Credit uses, including multi-valued attributes.

GET /Users

Response (200):
{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 3,
    "Resources": [
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "766b7824-ad5d-421d-8318-4fc0cdb2143e",
            "externalId": null,
            "userName": "employee1@email.com",
            "name": {
                "formatted": "George Washington",
                "familyName": "Washington",
                "givenName": "George"
            },
            "emails": [
                {
                    "value": "employee1@email.com",
                    "primary": true
                }
            ],
            "roles": [
                {
                    "displayName": "Your Company Name, ADMIN"
                }
            ],
            "active": true,
            "meta": {
                "resourceType": "User",
                "created": "2024-03-13T18:05:06.137Z",
                "lastModified": "2024-03-13T19:15:40.515Z",
                "location": "https://api.aphrodite.novacredit.com/user/sso/scim/Users/766b7824-ad5d-421d-8318-4fc0cdb2143e"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "282ab371-3dd5-42f4-b8bb-3e32e075928e",
            "externalId": "123",
            "userName": "employee2@email.com",
            "name": {
                "formatted": "Thomas Jefferson",
                "familyName": "Jefferson",
                "givenName": "Thomas"
            },
            "emails": [
                {
                    "value": "employee2@email.com",
                    "primary": true
                }
            ],
            "roles": [
                {
                    "displayName": "Your Company Name, ADMIN"
                }
            ],
            "active": true,
            "meta": {
                "resourceType": "User",
                "created": "2024-03-13T18:22:07.646Z",
                "lastModified": "2024-03-13T19:49:41.461Z",
                "location": "https://api.aphrodite.novacredit.com/user/sso/scim/Users/282ab371-3dd5-42f4-b8bb-3e32e075928e"
            }
        },
        {
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "8353a76b-6e67-4c44-8518-cfd81fd9cfc4",
            "externalId": null,
            "userName": "employee3@novacredit.com",
            "name": {
                "formatted": "John Adams",
                "familyName": "Adams",
                "givenName": "John"
            },
            "emails": [
                {
                    "value": "employee3@email.com",
                    "primary": true
                }
            ],
            "roles": [
                {
                    "displayName": "Your Company Name, VIEWER"
                }
            ],
            "active": true,
            "meta": {
                "resourceType": "User",
                "created": "2024-03-13T19:47:23.158Z",
                "lastModified": "2024-03-13T19:47:23.158Z",
                "location": "https://api.aphrodite.novacredit.com/user/sso/scim/Users/8353a76b-6e67-4c44-8518-cfd81fd9cfc4"
            }
        },
    ]
}

POST /Users

Request:
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
    ],
    "userName": "example@email.com",
    "externalId": "externalId1",
    "name": {
        "familyName": "Madison",
        "givenName": "James",
    },
    "roles": [
        {
            "displayName": "Child Org 1, ADMIN",
        },
        {
            "displayName": "Child Org 2, DEVELOPER",
        }
    ],
}

Response (201):
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "2b86b0a8-132f-4329-8efa-496b5001c374",
    "externalId": "externalId1",
    "userName": "example@email.com",
    "name": {
        "formatted": "James Madison",
        "familyName": "Madison",
        "givenName": "James"
    },
    "emails": [
        {
            "value": "example@email.com",
            "primary": true
        }
    ],
    "roles": [
        {
            "displayName": "Child Org 1, ADMIN"
        },
        {
            "displayName": "Child Org 2, DEVELOPER"
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": "2024-02-27T05:26:03.614Z",
        "lastModified": "2024-02-27T05:26:03.614Z",
        "location": "http://api.novacredit.com/user/sso/scim/Users/2b86b0a8-132f-4329-8efa-496b5001c374"
    }
}

PATCH /Users/:id

Request:
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{
        "op": "Replace",
        "path": "userName",
        "value": "replacementemail@email.com"
    }]
}

Response (200):
{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "id": "2b86b0a8-132f-4329-8efa-496b5001c374",
    "externalId": "externalId1",
    "userName": "example@email.com",
    "name": {
        "formatted": "James Madison",
        "familyName": "Madison",
        "givenName": "James"
    },
    "emails": [
        {
            "value": "replacementemail@email.com",
            "primary": true
        }
    ],
    "roles": [
        {
            "displayName": "Child Org 1, ADMIN"
        },
        {
            "displayName": "Child Org 2, DEVELOPER"
        }
    ],
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": "2024-02-27T05:26:03.614Z",
        "lastModified": "2024-02-27T05:26:03.614Z",
        "location": "http://api.novacredit.com/user/sso/scim/Users/2b86b0a8-132f-4329-8efa-496b5001c374"
    }
}

DELETE /Users/:id

The DELETE endpoint resolves with a 204 and does not return a response body.

Filters

The Nova Credit SCIM implementation supports filtering by all attributes for the GET /Users endpoint.

SCIM provisioning limitations

Users cannot be permanently deleted from Nova Credit, they can only be deactivated (soft deleted).
If Entra sends a hard delete to Nova any subsequent attempts to provision a new user with a duplicate email address will fail with a 409 error. If you need to reactivate a user, please contact support.
When creating a new user, if any fields are invalid, the provisioning will fail.
Group endpoints are not implemented, although groups can still be used for easier user management as long the iDP is configured to not push to these endpoints.

Manage people in a workspace​

Accessing the SCIM API​

Acquire a Bearer token​

Use the token in a SCIM API request​

Installing the Nova Credit app in Microsoft Entra​

Mapping roles​

Active attribute​

Installing the Nova Credit app in Okta​

Scim settings​

Mapping roles​

Schemas​

Endpoints​

User attributes​

Permissions​

Permissions per organization​

Example​

Filters​

SCIM provisioning limitations​

Manage people in a workspace

Accessing the SCIM API

Acquire a Bearer token

Use the token in a SCIM API request

Installing the Nova Credit app in Microsoft Entra

Mapping roles

Active attribute

Installing the Nova Credit app in Okta

Scim settings

Mapping roles

Schemas

Endpoints

User attributes

Permissions

Permissions per organization

Example

Filters

SCIM provisioning limitations