Initializing help system before first use

User admin resources

Operation Description
GET /api/admin/authority-groups

Get all authority groups
POST /api/admin/authority-groups

Create a new authority group
GET /api/admin/authority-groups/{id}

Get an authority group
DELETE /api/admin/authority-groups/{id}

Delete an authority group
PATCH /api/admin/authority-groups/{id}

Update an authority group
GET /api/admin/custom-authorities

Get all custom authorities
GET /api/admin/users

Get all users
POST /api/admin/users

Create a new user
GET /api/admin/users/{id}

Get a user
DELETE /api/admin/users/{id}

Delete a user
PATCH /api/admin/users/{id}

Update a user

GET /api/admin/authority-groups

Get all authority groups

Get all authority groups.

Security: SYS_USER is required to list authority groups.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The page of authority groups, sorted by name

Content-Type application/vnd.com.fico.xpress.insight.v2+json

PageOfAuthorityGroup

403 Forbidden

The current user was not authorized to list authority groups

POST /api/admin/authority-groups

Create a new authority group

The payload specifies the attributes of the new authority groups. All other attributes are mandatory.

Security: SYS_USER is required to create a new user.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

AuthorityGroup

Responses

201 Created

The created authority group

Content-Type application/vnd.com.fico.xpress.insight.v2+json

AuthorityGroup

Location

The URL of the created resource

 string
403 Forbidden

The current user was not authorized to create authority groups

409 Conflict

The name was already in use

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-409",
        "desc": "Conflict",
        "innerError": {
            "code": "OPTI-Insight-Locks-ConflictingNameUpdate",
            "desc": "Conflicting naming operation",
            "message": "An item with the same name already exists"
        },
        "message": "Conflict",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

The supplied payload was invalid

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/admin/authority-groups/{id}

Get an authority group

Get a single authority group by ID.

Security: SYS_USER is required to read an authority group.

Request Parameters

Name Description Type Data Type
id

The authority group ID

 path string (uuid) required

Responses

200 OK

The requested authority group

Content-Type application/vnd.com.fico.xpress.insight.v2+json

AuthorityGroup

403 Forbidden

The current user was not authorized to read this authority group

404 Not Found

The authority group did not exist

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

DELETE /api/admin/authority-groups/{id}

Delete an authority group

Delete an authority group.

Security: SYS_USER is required to delete an authority group.

Request Parameters

Name Description Type Data Type
id

the authority group ID

 path string (uuid) required

Responses

204 No Content

The authority group was successfully deleted

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Empty response body

403 Forbidden

The current user was not authorized to delete authority groups, or cannot remove SYS_USER from themself

PATCH /api/admin/authority-groups/{id}

Update an authority group

Update the properties of an authority group. Only the name, description and authorities can be changed. The objectType is optional, but if it is supplied then it must be AUTHORITY_GROUP. All other attributes are ignored.

Security: SYS_USER is required to edit an authority group.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

AuthorityGroup

Request Parameters

Name Description Type Data Type
id

The authority group ID

 path string (uuid) required

Responses

200 OK

The updated authority group

Content-Type application/vnd.com.fico.xpress.insight.v2+json

AuthorityGroup

403 Forbidden

The current user was not authorized to update this authority group, or cannot remove SYS_USER from themself

409 Conflict

The updated name was already in use

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-409",
        "desc": "Conflict",
        "innerError": {
            "code": "OPTI-Insight-Locks-ConflictingNameUpdate",
            "desc": "Conflicting naming operation",
            "message": "An item with the same name already exists"
        },
        "message": "Conflict",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

Validation of the requested changes failed, e.g. the name was too long

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/admin/custom-authorities

Get all custom authorities

Get all custom authorities.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The page of custom authorities

Content-Type application/vnd.com.fico.xpress.insight.v2+json

PageOfCustomAuthority

403 Forbidden

The current user was not authorized to read the custom authorities

GET /api/admin/users

Get all users

Get all users.

Security: SYS_USER is required to list users.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The page of users

Content-Type application/vnd.com.fico.xpress.insight.v2+json

PageOfUser

403 Forbidden

The current user was not authorized to read users

POST /api/admin/users

Create a new user

Create a new user.

Security: SYS_USER is required to create a new user and current user must be logged in locally.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

UserCreationRequest

Responses

201 Created

The created user

Content-Type application/vnd.com.fico.xpress.insight.v2+json

User

Location

The URL of the created resource

 string
403 Forbidden

The current user was not authorized to create users

409 Conflict

The username was already in use

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-409",
        "desc": "Conflict",
        "innerError": {
            "code": "OPTI-Insight-Locks-ConflictingNameUpdate",
            "desc": "Conflicting naming operation",
            "message": "An item with the same name already exists"
        },
        "message": "Conflict",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

The request was not well-formed. For example, a referenced app did not exist.

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Invalid user status",
            "message": "Cannot lock user in non-local authentication mode"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/admin/users/{id}

Get a user

Get a user by ID.

Security: SYS_USER is required to read a user.

Request Parameters

Name Description Type Data Type
id

The user ID

 path string (uuid) required

Responses

200 OK

The user

Content-Type application/vnd.com.fico.xpress.insight.v2+json

User

403 Forbidden

The current user was not authorized to read this user

404 Not Found

The user did not exist or was unavailable to the current user

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

DELETE /api/admin/users/{id}

Delete a user

Deletes a user by ID.

Security: SYS_USER is required to delete a user and current user must be logged in locally.

Request Parameters

Name Description Type Data Type
id

The user ID

 path string (uuid) required

Responses

204 No Content

The user was successfully deleted

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Empty response body

403 Forbidden

The current user was not authorized to delete the user, or cannot delete themself

404 Not Found

The user did not exist

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

PATCH /api/admin/users/{id}

Update a user

The payload contains the updates to apply to the user. They are all optional.

The first name, last name, email and status fields are optional. The status cannot be DELETED.

The user id attribute is optional, but if it is supplied then it must match the id in the URL.

The user's app membership will be updated to the supplied list of apps. Their membership is unchanged if this attribute is missing or null.

If authority groups are supplied, they will replace the existing ones.

The objectType is optional, but if it is supplied then it must be USER.

All other attributes are ignored.

When using SAML2 authentication, the first name, last name, email and status fields can only be edited in the Identity Provider - if specified here they will be ignored.

Attempting to change the current user's status to a non ACTIVE status will result in a 422 error.

Updating the current user's authority groups so that they no longer have the SYS_USER role will also result in a 422 error.

Security: SYS_USER is required to edit a user.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

User

Request Parameters

Name Description Type Data Type
id

The user ID

 path string (uuid) required

Responses

200 OK

The updated user

Content-Type application/vnd.com.fico.xpress.insight.v2+json

User

403 Forbidden

The current user was not authorized to update this user,or cannot deactivate themself, or cannot remove SYS_USER from themself

404 Not Found

The user did not exist or was unavailable to the current user

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
409 Conflict

The updated name was already in use

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-409",
        "desc": "Conflict",
        "innerError": {
            "code": "OPTI-Insight-Locks-ConflictingNameUpdate",
            "desc": "Conflicting naming operation",
            "message": "An item with the same name already exists"
        },
        "message": "Conflict",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

Validation of the requested changes failed. e.g. the name was too long or an app or authority group did not exist.

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Mismatched ID in request path and content",
            "message": "IDs must match, found \\'00000000-4995-29d9-0000-000194a8f472\\' in URL but \\'00000001-94a8-f472-0000-0000499529d9\\' in request body"
        },
        "message": "Unprocessable Entity",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

AuthorityGroup: object

A group of authorities that can be assigned to user accounts.

Properties

authorities: string[]

The authorities in this group

Array of string , one of { APP_ALL , APP_ATTACHMENT_EDIT , APP_ATTACHMENT_VIEW , APP_DELETE , APP_EDIT , APP_EXPORT , APP_NEW , DEVELOPER , DIRECT_DATA_VIEW , FOLDER_DELETE , FOLDER_EDIT , FOLDER_NEW , FOLDER_OWNER , FOLDER_SHARE , SCENARIO_ALL , SCENARIO_ATTACHMENT_EDIT , SCENARIO_DELETE , SCENARIO_EDIT , SCENARIO_EXEC , SCENARIO_NEW , SCENARIO_OWNER , SCENARIO_SHARE , SYS_IMPORTEXPORT , SYS_SERVER , SYS_SERVICES , SYS_USER }
customAuthorities: object[]

The custom authorities in this group

Array of CustomAuthority
description: string (up to 255 chars)

The description of this authority group

Example: 
"Default group of authorities assigned to managers"
executionServices: object[]

The execution services permitted by this group

Array of ReferenceExecutionService
id: string (uuid)

The ID of this authority group

Example: 
"e41f940c-f974-b034-1be0-6bf33086fd89"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this authority group

Example: 
"My authority group"
objectType: string , one of { AUTHORITY_GROUP }
url: string (uri)

The URL of this authority group

Example: 
"/api/admin/authority-groups/e41f940c-f974-b034-1be0-6bf33086fd89"

CustomAuthority: object

An authority defined by an app

Properties

name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The authority's name

Example: 
"FOLDER_ATTACHMENT_EDIT"

ErrorDetail: object

An error detail

Properties

code: string

The unique code for this error

Example: 
"FICO_PLATFORM_VALIDATION_INVALID_VALUE"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
target: string

An identifier to help the client locate the error. Typically a JSON property name.

timestamp: string (date-time)

When the error was first detected

ErrorResponse: object

An error response containing fault or error information

Properties

error:

The top level error

InnerError: object

More specific error information

Properties

code: string

The unique code for this error

Example: 
"FICO-Platform-Validation-FileTooLarge"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Attachment upload too large"
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Files larger than 300 MB cannot be uploaded as attachments."

OuterError: object

The top level error

Properties

code: string , one of { FICO-Platform-Http-400 , FICO-Platform-Http-404 , FICO-Platform-Http-409 , FICO-Platform-Http-413 , FICO-Platform-Http-422 , FICO-Platform-Http-423 , FICO-Platform-Http-429 , FICO-Platform-Http-500 , FICO-Platform-Http-503 }

The unique code for this error

Example: 
"FICO-Platform-Http-409"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
details: object[]

Details about specific errors that led to this reported error

Array of ErrorDetail
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
parentId: string

An OpenTracing parent-span ID

Example: 
"0020000000000001"
spanId: string

An OpenTracing span ID

Example: 
"b2fb4a1d1a96d312"
timestamp: string (date-time)

When the error was first detected

traceId: string

An OpenTracing trace ID

Example: 
"463ac35c9f6413ad48485a3953bb6125"

PageOfAuthorityGroup: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of AuthorityGroup
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

PageOfCustomAuthority: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of CustomAuthority
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

PageOfUser: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of User
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

ReferenceApp: object

The basic details of an app

Properties

id: string (uuid)

The ID of this app

Example: 
"00007eff-83f9-05fe-ffff-81007c05fc01"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this app

Example: 
"My app"
objectType: string , one of { APP }
url: string (uri)

The URL of this app

Example: 
"/api/apps/00007eff-83f9-05fe-ffff-81007c05fc01"

ReferenceAuthorityGroup: object

The basic details of an authority group

Properties

id: string (uuid)

The ID of this authority group

Example: 
"e41f940c-f974-b034-1be0-6bf33086fd89"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this authority group

Example: 
"My authority group"
objectType: string , one of { AUTHORITY_GROUP }
url: string (uri)

The URL of this authority group

Example: 
"/api/admin/authority-groups/e41f940c-f974-b034-1be0-6bf33086fd89"

ReferenceExecutionService: object

Properties

id: string (uuid)

The ID of this execution service

Example: 
"8aadc318-75b3-3bee-7552-3ce8030b27c4"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this execution service

Example: 
"My execution service"
objectType: string , one of { EXECUTION_SERVICE }
url: string (uri)

The URL of this execution service

Example: 
"/api/admin/execution/services/8aadc318-75b3-3bee-7552-3ce8030b27c4"

Sort: object

Details of how paged results were sorted

Properties

empty: boolean

True if there are no results

Example: 
false
sorted: boolean

True if the results are sorted

Example: 
false
unsorted: boolean

True if the results are not sorted

Example: 
false

User: object

A user

Properties

apps: object[]

The apps which this user has access to

Array of ReferenceApp
authorityGroups: object[]

The authority groups granted to this user

Array of ReferenceAuthorityGroup
email: string

The email address of this user

firstName: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

This user's first name

Example: 
"William"
id: string (uuid)

The ID of this user

Example: 
"0013ebae-4d4c-793c-ffec-1451b28ba2f9"
lastName: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

This user's last name

Example: 
"Sweet"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this user

Example: 
"William Sweet"
objectType: string , one of { USER }
password: string

The new user's password

status: string , one of { ACTIVE , DELETED , DISABLED , LOCKED }

The status of this user's account

url: string (uri)

The URL of this user

Example: 
"/api/admin/users/0013ebae-4d4c-793c-ffec-1451b28ba2f9"
username: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

This user's username

Example: 
"williamsweet"

UserCreationRequest: object

A request to create a new user

Properties

apps: object[]

The apps which this user has access to

Array of ReferenceApp
authorityGroups: object[]

The authority groups granted to this user

Array of ReferenceAuthorityGroup
email: string

The new user's email address

firstName: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The new user's first name

Example: 
"William"
lastName: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The new user's last name

Example: 
"Sweet"
name: string

The new user's name

Example: 
"William Sweet"
password: string

The new user's password

status: string , one of { ACTIVE , DELETED , DISABLED , LOCKED }

The status of the new user's account

username: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The new user's username

Example: 
"williamsweet"
Parent Topic Insight 5 REST API

© 2001-2022 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.