API

API Creation

Add a usable script

  • Add a new script
  • Add a new API key if required
  • Edit the API key
  • Provide the allowed IPs and select the new script
  • Click on the script to see a sample command Example :

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:

Response:

Users

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;
primaryDirectory?: DirectoryID;
allDirectories?: DirectoryID[];
groups?: {
    id: GroupID;
    name: string;
}[];
}

Create

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;
    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 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, an expiration and a redirect can complete the link.
  • 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
  • isAdmin has an invalid format
  • passwordInit has an invalid format
  • A group has an invalid format
  • A group doesn’t exist

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

Update a specific user by id

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

Description:

  • Update a user defined by his id with the given parameters: firstName, lastName, email, email2.
  • 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
  • isAdmin has an invalid format
  • suspended has an invalid format
  • A group has an invalid format
  • The email already exists

Delete

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

Return the list of users in the organization

listUsers(args: { withGroups?: 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.

Groups

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.

Applications

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.

Permissions

Datatype

interface Perm {
    appID: AppID;
    groupID: GroupID;
    userID: UserID;
    internalZone: ZoneSecurityLevel;
    externalZone: 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.
  • The zone can be either internal (public IP addresses of the internal network) or external (any other IP address).
  • 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.
  • Not Specified: 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
  • Default perms: internal -> 1 factor, external -> 2 factors
  • Perm Customer Success for salesforce: internal -> 1 factor, external -> 2 factors
  • Perm Support for salesforce: internal -> 2 factors, external -> forbidden
  • Perm John Doe for salesforce: internal -> not specified, external -> 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;
}): { 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.
  • 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
  • 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;
}): { 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.
  • 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
  • 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;
}[];

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 internalZone and externalZone.

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;
}[];

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 internalZone and externalZone.

Possible errors:

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

Logs

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

Alerts

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

Sessions

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.

AuthToken

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:

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:

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:

Sms received with the code: 123456

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

Response:

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:

Notification received then accepted on Trustelem Authenticator

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

Response: