API

Add a usable script

1-Add a new script

2-Add a new API key if required

3-Edit the API key

4-Provide the allowed IPs and select the new script

5-Click on the script to see a sample command

Example:

Name: create_user
Sample command:
  curl -X POST -H 'Authorization: Bearer ZPUAtMc...KYYAej4e' https://admin.trustelem.com/api/script/46e3xi...gtea/create_user

Edit the script

function handler: contains the script in TypeScript language

type Input: contains the parameters required to launch the script

type Output: contains the result which will be provided by the script

Note: you can start from scratch or load examples:

• Click on Examples and select what you want to import

• Click on Load

Example with the script simple_create_user

function handler contains:

//Create the input with the provided parameters
const input = req.ReadJSON(true);
//Call the API create user with the previous parameters
const result = api.createUser({
    email: input.email,
    firstName: input.firstname,
    lastName: input.lastname,
    passwordInit: { kind: 'temporaryPassword' }
});
//If there is an error, send it as the result
if (isError(result)) {
    w.JSON({ error: result.error })
} else {
//Else, provide the temporary password as the result
w.JSON({ password: result.temporaryPassword });
}

type Input contains the provided parameters:

{
    email: string;
    firstname: string;
    lastname: string;
}

type Output contains the result parameters:

{
    password: string;
    } | {
    error: string;
}

API request:

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer yyhp3yD…lWfxfl8J' -d '{"email":"jdoe@test.com","firstname":"John","lastname":"Doe"}' https://admin.trustelem.com/api/script/wg5…qia/create_user

Response:

{"password":"mkrc2o6mo2ka"}

Datatype

interface User {
id: UserID;
firstName: string;
lastName: string;
UUID?: string;
userPrincipalName?: string;
email: string;
email2?: string;
mobilePhone?: string;
secondaryPhone?: string;
trustelemAdmin?: boolean;
suspended?: boolean;
accountExpiration?: string
primaryDirectory?: DirectoryID;
allDirectories?: DirectoryID[];
attributes?: AttributeManager;
groups?: {
    id: GroupID;
    name: string;
}[];
}

Note: the attributes can be request using getValue, getValues or list

interface AttributeManager { getValue(name: string): string | null; getValues(name: string): string[]; list: { name: string; value: string }[] };

Create a user

Create a new user, if sendActivationEmail is true, send a mail for setting password, InitPWD will be filled otherwise

createUser(args: {
    email: string;
    email2?: string;
    firstName?: string;
    lastName?: string;
    accountExpiration?: Date | number | string | null;
    isAdmin?: boolean;
    groups?: GroupID[];
    passwordInit?: { kind: 'temporaryPassword' } | { kind: 'link'; expireMinutes?: number; redirectURL?: string; openSession?: boolean };
}): { id: UserID; temporaryPassword: string; passwordInitURL: string } | { error: string };

Description:

• Create a user with chosen firstName, lastName, email1, email2.
• Only the email1 is mandatory.
• This user access can expire at a given date using the parameter accountExpiration.
• This user can be granted with administrator privileges with the parameter isAdmin.
• This user can be added to groups defined by their GroupID.
• The activation is defined by the passwordInit which can be set to 'temporaryPassword' or 'link'.
• In the second case, a validity (24h if empty) and a redirectURL can complete the link. Also, the session can be directly open or not with the parameter openSession.
• The outputs will be either the new user id and possibly his temporaryPassword / passwordInitURL or the error(s).

Possible errors:

• The email1 already exists
• The email1 has an invalid format
• The email1 is mandatory
• The email2 has an invalid format
• The firstName has an invalid format
• The lastName has an invalid format
• accountExpiration has an invalid format
• isAdmin has an invalid format
• passwordInit has an invalid format
• A group has an invalid format
• A group doesn’t exist
• kind has an invalid format
• expireMinutes has an invalid format
• redirectURL has an invalid format
• openSession has an invalid format

Read a user

Get a specific user by id, email or upn

getUser(args: {
    id?: UserID;
    email?: string;
    userPrincipalName?: string;
}): User | null;

Description:

• If a user defined by a given id, email or userPrincipalName exists, provide his attributes.

Update a user

Update a specific user by id

updateUser(args: {
    id: UserID;
    firstName?: string;
    lastName?: string;
    email?: string;
    email2?: string;
    isAdmin?: boolean;
    suspended?: boolean;
    accountExpiration?: Date | number | string | null;
    groups?: GroupID[];
}): { error?: string; };

Description:

• Update a user defined by his id with the given parameters: firstName, lastName, email, email2.
• This user'access can expire at a given date using the parameter accountExpiration
• This user can be granted with administrator privileges with the parameter isAdmin sets to true.
• This user can be suspended with the parameter suspended sets to true.
• This user can also be affected to groups with the parameter groups.
• The outputs will be either nothing, or the error(s).

Possible errors:

• The user id doesn’t exist
• A group doesn’t exist
• The user id is mandatory
• The user id has an invalid format
• The firstName has an invalid format
• The lastName has an invalid format
• The email has an invalid format
• The email2 has an invalid format
• accountExpiration has an invalid format
• isAdmin has an invalid format
• suspended has an invalid format
• A group has an invalid format
• The email already exists

Delete users

Remove specific users by id

deleteUsers(args: { users: UserID[]; }): {
    deleted: {
        id: UserID;
        email: string;
    }[];
    errors?: string[];
};

Description:

• Delete a list of users defined by their id.
• The outputs will be either the email and the user id of the deleted users or the error(s).

Possible error:

• A user doesn’t exist
• The list of users has an invalid format
• The list of users is mandatory

Search users

Return the list of users in the organization

listUsers(args: {
    withGroups?: boolean;
    withAttributes?: boolean;
}): User[];

Description:

• List all users with their attributes.
• If the parameter withGroups is set to true, the fields groups of each user will be filled with the lists of groups (name and id) the user is member of.
• If the parameter withAttributes is set to true, the fields attributes of each user will be filled with the lists of their attributes.

Add or Set Trustelem user attributes

Add a value (or several values) to a Trustelem user attribute.

addUserAttr(args: {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Set the value (or the values) of a Trustelem user attribute.
This function deletes all previously existing values for this Trustelem attribute.

setUserAttr(args: {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Description:

• Create or replace a Trustelem attribute for a user defined by its userID.
• The attribute has a name and can have a value or multiple values.
• The output will be either nothing, or the error(s).

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The name has an invalid format
• The values have ab invalid format
• The userID is mandatory
• The name is mandatory
• The values is mandatory

Delete Trustelem user attributes

Delete one or more Trustelem attribute values from a user:

delUserAttr(args: {
    userID: UserID;
    name: string;
    all: true;
} | {
    userID: UserID;
    name: string;
    value: string;
} | {
    userID: UserID;
    name: string;
    values: string[];
}): { error?: string; };

Description:

• Delete a Trustelem attribute for a user defined by its userID.
• If 'all' is provided, all attributes with the given name are deleted ;
• If 'value' is provided, only the attributes with the given name and this value are deleted ;
• If 'values' is provided, only the attributes with the given name and a value which matches one of the provided values are deleted.

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The name has an invalid format
• The values have ab invalid format
• The userID is mandatory
• The name is mandatory
• The parameters all or values are mandatory

Reset a user password

Generate a code or a link allowing a user to reset its password

resetPassword(args: {
    id: UserID;
    method?: { kind: 'code'; expireMinutes?: number } | { kind: 'link'; expireMinutes?: number; redirectURL?: string; openSession?: boolean };
}): { resetCode: string; resetLink: string; expirationDate: string } | { error: string };

Description:

• Reset the password of a user defined by his userID.
• The reset is defined by the attribute method, which can be set to 'code' or 'link'.
• Both method have an attribute expireMinutes to define its validity (24h if empty).
• The method link has also a redirectURL and the possibility to open a Trustelem session after the definition of the new password.
• The output will be either nothing or the error.

Possible errors:

• The userID doesn't exist
• The userID has an invalid format
• kind has an invalid format
• expireMinutes has an invalid format
• redirectURL has an invalid format
• openSession has an invalid format

Datatype

interface Group {
    id: GroupID;
    name: string;
    UUID: string;
    directoryID?: DirectoryID;
}

Create

Create a new group

createGroup(args: {
    name: string;
    users?: UserID[];
}): { id: GroupID } | { error: string };

Description:

• Create a group with the given name.
• The group can contain a list of users defined by their UserID.
• The outputs will be either the id of the new group or the error(s).

Possible errors:

• The name already exists
• The name is mandatory
• The name has an invalid format
• A user doesn’t exist
• A user has an invalid format

Read member

List users from groups

getGroupMembers(args: { id: GroupID; }): {
    users: {
        userID: UserID;
        email: string;
    }[];
};

Description:

• Provide the userID and the email of users, member of given groups defined by their id(s).

Update

Add user(s)

Add a list of users to a group

addUsersToGroup(args: {
    id: GroupID;
    users: UserID[];
}): { Added: UserID[] } | { error: string };

Description:

• Add a list of users defined by their UserID to a group defined by its GroupID.
• The outputs will be either the UserID of the added users, or the error(s).

Possible errors:

• The id doesn’t exist
• A user doesn’t exist
• The id has an invalid format
• A user has an invalid format
• The id is mandatory
• The list of users is mandatory

Remove user(s)

Remove a list of users from a group

removeUsersFromGroup(args: {
    id: GroupID;
    users: UserID[];
}): { Removed: UserID[] } | { error: string };

Description:

• Remove a list of users defined by their UserID from a group defined by its GroupID.
• The outputs will be either the UserID of the removed users, or the error(s).

Possible errors:

• The id doesn’t exist
• A user doesn’t exist
• The id has an invalid format
• A user has an invalid format
• The id is mandatory
• The list of users is mandatory

Delete

Delete a group not synchronized from a directory

deleteGroup(args: { id: GroupID; }): { error?: string; };

Description:

• Delete a group defined by its id.
• The outputs will be either nothing or the error(s).

Possible error:

• The group id doesn’t exist
• A group id has an invalid format
• The group id is mandatory

Search

By id

Get a specific group by id

getGroup(args: {
    id?: GroupID;
    name?: string;
}): Group | null;

Description:

• If a group defined by a given id or name exists, provide its attributes.

List

Return the list of groups in the organization

listGroups(args: {}): Group[];

Description:

• List all the existing groups with their attributes.

Datatype

interface App {
    id: AppID;
    name: string;
}

List

Return the list of applications in the organization

listApps(args: {}): App[];

Description:

• List all the existing applications with their attributes.

Search

Get a specific App by id

getApp(args: {
    id?: AppID;
    name?: string;
}): App | null;

Description:

• If an application defined by a given id or name exists, provide its attributes.

Datatype

interface Perm {
    appID: AppID;
    groupID: GroupID;
    userID: UserID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone: ZoneSecurityLevel;
    radiusZone: ZoneSecurityLevel;
}

type ZoneSecurityLevel = '' | 'default' | '1_factor' | '2_factors' | 'forbidden';

Description:

• ZoneSecurityLevel represents the permission level for a group or a user to access an app depending of an IP zone or protocols.
• The zone can be either internal (public IP addresses of the internal network), external (any other IP address), LDAP or RADIUS.
• The effective permission for a user is based on the default access-rules, then overload by one or many permissions based on the groups, then overload again by the permissions of the user.
• In case of multiple groups permissions, the more restrictive is applied.

The ZoneSecurityLevel can be one of the 5 following values:

• '' or no rule: does not apply any rule so other permissions can remain active.
• default: apply the default rule
• One Factor: only one authentication factor is needed to access the application
• Two Factor: two authentication factors are needed to access the application
• Forbidden: the user can’t access the application

Examples:

John Doe is in groups “Customer Success” and “Support”

Permissions defined:

• Customer Success for salesforce: internal -> 1 factor, external -> 2 factors
• Support for salesforce: internal -> 2 factors, external -> forbidden
• John Doe for salesforce: internal -> not specified, external -> 2 factors

For internal zone we have 1 factor and 2 factors for groups and not specified for user --> 2 factors For external zone we have 2 factors and forbidden for groups and 2 factors for user --> 2 factors

John needs 2 factors to access salesforce for both internal and external zone.

List

Return the list of permissions for a user, a group or an application

listPerms(args: {
    userID?: UserID;
    groupID?: GroupID;
    appID?: AppID;
}): { perms: Perm[] } | { error: string };

Description:

• List all the permissions available for a user defined by his userID or a group defined by its groupID or an application defined by its appID.
• The research is done on only one id, the priority order is userID, then groupID, then appID.

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The groupID doesn’t exist
• The groupID has an invalid format
• The appID doesn’t exist
• The appID has an invalid format

Set

For group

Create or update a permission for a group

setGroupPerm(args: {
    groupID: GroupID;
    appID: AppID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone?: ZoneSecurityLevel;
    radiusZone?: ZoneSecurityLevel;
}): { error?: string; };

Description:

• Create or update a permission for a group defined by its groupID, to an application defined by its appID.
• The permission level must be defined for the internalZone and the externalZone with a ZoneSecurityLevel.
• A specific permission is needed for LDAP and RADIUS protocols
  If only ldap/radius are needed, fixe the internal/external zones at ' ' which is no rule
• The outputs will be either nothing, or the error(s).

Possible errors:

• The groupID doesn’t exist
• The appID doesn’t exist
• internalZone has an invalid format
• externalZone has an invalid format
• radiusZone has an invalid format
• ldapZone has an invalid format
• The appID has an invalid format
• The groupID has an invalid format
• internalZone is mandatory
• externalZone is mandatory
• The appID is mandatory
• The groupID is mandatory

For User

Create or update a permission on a user

setUserPerm(args: {
    userID: UserID;
    appID: AppID;
    internalZone: ZoneSecurityLevel;
    externalZone: ZoneSecurityLevel;
    ldapZone?: ZoneSecurityLevel;
    radiusZone?: ZoneSecurityLevel;
}): { error?: string; };

Description:

• Create or update a permission for a user defined by his userID, to an application defined by its appID.
• The permission level must be defined for the internalZone and the externalZone with a ZoneSecurityLevel.
• A specific permission is needed for LDAP and RADIUS protocols
  If only ldap/radius are needed, fixe the internal/external zones at '' which is no rule
• The outputs will be either nothing, or the error(s).

Possible errors:

• The userID doesn’t exist
• The appID doesn’t exist
• internalZone has an invalid format
• externalZone has an invalid format
• radiusZone has an invalid format
• ldapZone has an invalid format
• The appID has an invalid format
• The userID has an invalid format
• internalZone is mandatory
• externalZone is mandatory
• The appID is mandatory
• The userID is mandatory

Delete

Delete a permission for a user, or a group to an application

deletePerm(args: {
    userID?: UserID;
    groupID?: GroupID;
    appID: AppID;
}): { error?: string; };

Description:

• Delete a permission granted to a user or a group to access an application. The three previous parameters are defined by their ID.
• The outputs will be either nothing or the error(s).

Possible errors:

• The groupID doesn’t exist
• The userID doesn’t exist
• The appID doesn’t exist
• The groupID has an invalid format
• The userID has an invalid format
• The appID has an invalid format
• The appID is mandatory

Read

For user

Return consolidated (computed from list of permissions) permissions for a user

getEffectiveAppsPermsForUser(args: { userID: UserID; }): {
    appID: AppID;
    appName: string;
    internalZone: EffectiveZoneSecurityLevel;
    externalZone: EffectiveZoneSecurityLevel;
    ldapZone: EffectiveZoneSecurityLevel;
    radiusZone: EffectiveZoneSecurityLevel;
}[];

Description:

• For a given user defined by his userID, return the list of the application(s) he can access, defined by their appID and appName, with the permissions for internal, external, ldap and radius zones.

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The userID is mandatory

For app

Return consolidated (computed from list of permissions) permissions for an app

getEffectiveUserPermsForApp(args: { appID: AppID; }): {
    userID: UserID;
    internalZone: EffectiveZoneSecurityLevel;
    externalZone: EffectiveZoneSecurityLevel;
    ldapZone: EffectiveZoneSecurityLevel;
    radiusZone: EffectiveZoneSecurityLevel;
}[];

Description:

• For a given application defined by its appID, return the list of users who can access to it, defined by their userID, with the permissions for internal, external, ldap and radius zones.

Possible errors:

• The appID doesn’t exist
• The appID has an invalid format
• The appID is mandatory

Datatype

interface Log {
    id: LogID;
    date: string;
    level: string;
    msg: string;
    details?: string;
    userID?: UserID;
    userEmail: string;
    ip: string;
    useragent: string;
}

List

Return the list of logs in the organization

listLogs(args: { start?: Date, end?: Date, order?: 'fromEnd' | 'fromStart', pageSize?: number, pageToken?: string }): { logs: Log[]; nextPageToken: string } | { error: string; };

Description:

• List all the logs of the 30 previous days.
• This list can be filtered by date with the parameter start / end to shorten the period.
  (Date format: RFC3339 "2006-01-02T15:04:05Z07:00")
• By default, a page displays 1000 logs, but it can be reduced with the parameter pageSize.
• The page can be ordered with the parameters ‘fromEnd’ or ‘fromStart’
• If one page is not enough, a nextPageToken is provided. It can be used as a pageToken in the API in order to access to a specific page.
• The outputs will be the logs, possibly the nextPageToken or the error(s).

Possible errors:

• start has an invalid format
• end has an invalid format
• order has an invalid format
• pageSize has an invalid format
• pageToken has an invalid format
• pageToken doesn’t exist

Datatype

interface Alert {
    id: AlertID;
    date: string;
    msg: string;
    userID: string;
    read: boolean;
}

List

List the alerts

listAlerts(args: {
    unreadOnly?: boolean;
    since?: string;
}): Alert[];

Description:

• List all the alerts of the 30 previous days.
• This list can be filtered by date with the parameter since to shorten the period.
• This list can provide only the unread alerts with the parameter unreadOnly set to true.

Acknowledge

Update an alert to be marked as read

markAlertAsRead(args: { alertID: AlertID; }): { error?: string; };

Description:

• Change the status of an alert, defined by its alertID, from unread to read.
• The outputs will be either nothing, or the error(s).

Possible errors:

• The alertID doesn’t exist
• The alertID has an invalid format
• The alertID is mandatory

Datatype

interface Session {
    id: SessionID;
    kind: string;
    userID: UserID;
    created: string;
    modified: string;
    expires: string;
    deleted: boolean;
    ip: string;
    userAgent: string;
}

List

List the sessions

listSessions(args: {
    showDeleted?: boolean;
    since?: string;
    limit?: number;
}): Session[];

Description:

• List the active sessions.
• This list can also contain the deleted sessions of the 30 previous days with the parameter showDeleted sets at true.
• This list can be filtered by date with the parameter since to shorten the period.
  (Date format: RFC3339 "2006-01-02T15:04:05Z07:00")
• By default, a page contains maximum 10000 sessions, but it can be reduced with the parameter limit.

Datatype

interface AuthToken {
    id: AuthTokenID;
    userID: UserID;
    kind: TokenKind;
    name: string;
}

List

List the second factors of a user

listAuthTokens(args: { id: UserID; }): { authTokens: AuthToken[] } | { error: string };

Description:

• For a given user defined by his id, list his authTokens available.
• The outputs will be either the authTokens, or the error(s).

Possible errors:

• The id doesn’t exist
• The id has an invalid format
• The id is mandatory

Issue

Send a challenge to a second factor

issueAuthToken(args: {
    userID: UserID;
    tokenID: AuthTokenID;
    message?: string;
}): { challengeID: ChallengeID } | { error: string };

Description:

• Send a challenge to a user defined by his userID on a chosen authToken defined by its tokenID.
• The challenges might be, for instance, a code in a SMS or a notification on a phone and if the factor supports it, can contain a message.
• The outputs will be either the challengeID, or the error(s).

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The userID is mandatory
• The tokenID doesn’t exist
• The tokenID has an invalid format
• The tokenID is mandatory

Verify

Verify the answer to a second factor challenge

verifyAuthToken(args: {
    userID: UserID;
    challengeID?: ChallengeID;
    tokenID?: AuthTokenID;
    passCode?: string;
}): { status: 'success' | 'waiting' | 'rejected' | 'timeout' | 'failed' } | { error: string };

Description:

• For a given user defined by his userID, verify the validity of an authToken defined by its challengeID or its tokenID.
• It is validated if the user accepts the authentication for Trustelem Authenticator, or provides the right passCode for the others authTokens.
• The outputs will be either: the status of the verification or the error(s).

Possible errors:

• The userID doesn’t exist
• The userID has an invalid format
• The userID is mandatory
• The challengeID doesn’t exist
• The challengeID has an invalid format
• The tokenID doesn’t exist
• The tokenID has an invalid format
• The passCode has an invalid format

Example

List the available authtokens

Script used:

let res: Output = api.listAuthTokens({
    id: "u68446589",
});

Response:

{"authTokens":[
{"id":"at1798391","userID":"u68446589","kind":"GA","name":"default"},
{"id":"at1954553","userID":"u68446589","kind":"TLM_AUTH","name":"samsung"},
{"id":"at1954598","userID":"u68446589","kind":"SMS","name":""}
]}

Use API to verify the factor Google Authenticator

Code provided by Google Authenticator: 123456

Script used:

//{"ID":"at1798391","UserID":"u68446589","Kind":"GA","Name":"default"}
let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    //challengeID: "",
    tokenID: "at1798391",
    passCode: "123456"
});

Response:

{"status":"success" }

Use API to verify the factor SMS

Script used:

{"ID":"at1954598","UserID":"u68446589","Kind":"SMS","Name":""}
let res: Output = api.issueAuthToken({
    userID: "u68446589",
    tokenID: "at1954598",  
});

Response:

{"challengeID":"c_6a809214faf216e33cfbc668a346f136"}

Sms received with the code: 123456

Script used:

let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    challengeID: "c_6a809214faf216e33cfbc668a346f136",
    //tokenID: "",
    passCode: "123456"
});

Response:

{"status":"success" }

Use API to verify the factor Trustelem Authenticator

Script used:

{"ID":"at1954553","UserID":"u68446589","Kind":"TLM_AUTH","Name":"samsung"}
let res: Output = api.issueAuthToken({
    userID: "u68446589",
    tokenID: "at1954553",  
});

Response:

{"challengeID":"c_6a809214faf216e33cfbc668a346f137"}

Notification received then accepted on Trustelem Authenticator

Script used:

let res: Output = api.verifyAuthToken({
    userID: "u68446589",
    challengeID: "c_6a809214faf216e33cfbc668a346f137",
    //tokenID: "",
    //passCode: ""
});

Response:

{"status":"success" }