• Register

User Management API

The User Management API allows you to create, update, get information about, and delete users. You can customize settings like user role or authentication type and even control whether a new user receives an invitation email.

To get user information to an OAUTH Token please click here.

Note that the endpoint for the User Management API should always begin like this:

https://{Egnyte Domain}.egnyte.com

Specific endpoints are listed with each method.

Note that this API adheres to the SCIM (System for Cross-domain Identity Management) standard for user management.

Common HTTP Headers

HTTP Request Headers

Header Description Value
Content-Type Specifies the format of request body application/json
Authorization This must use the the OAuth token you obtained through the OAuth flow. Bearer {OAuth token}

HTTP Response Headers

Header Description Value
Content-Type Specifies the format of response body application/json

Common Response Codes

Error Description
200 or 201 Successful operation
400 Request is syntactically incorrect or violates schema
401 Authentication failure
403 Server does not support requested operation
500 Internal server error

Error Messages

Errors are returned in the HTTP Status Code of the response. Human readable error messages are returned in an “Errors” JSON object in the response body. An example is shown below.

 HTTP/1.1 404 NOT FOUND

{
    "Errors": [
        {
             "description": "User 12345678 not found.",
             "code": "404"
       }
    ]
}

API Methods

Note that endpoints described below are v2, unlike the other endpoints within the Egnyte API.

Get Single User

Retrieves a single user.

GET /pubapi/v2/users/{id}

Method-specific Response Header:

Header Description Value
Location Specifies the URL location for a user, including the user ID. https://domain.egnyte.com/pubapi/v2/users/{id}

Sample Response Body

{
    "id": 12345678,
    "userName": "jmiller",
    "externalId": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "email": "john.miller@example.com",
    "name": {
        "familyName": "Miller",
        "givenName": "John"
    },
    "active": true,
    "createdDate": "2015-12-22T04:56:07.000+0000",
    "lastModificationDate": "2018-05-10T07:54:54.000+0000",
    "lastActiveDate": "2016-08-10T15:52:07.000+0000",
    "locked": false,
    "authType": "sso",
    "userType": "admin",
    "idpUserId": "jmiller",
    "isServiceAccount": false,
    "language: "en-US",
    "deleteOnExpiry": null,
    "emailChangePending": false,
    "expiryDate": null,
    "role": null,
    "userPrincipalName": null,
    "groups": [{
        displayName: "Marketing Team",
        value: "1ee2e04c-bdde-42ee-ae07-c3aad375f6da"
    }, {
        displayName: "Project Alpha",
        value: "9125a8dc-52ee-365b-a5aa-81b0b3681cf6"
    }]
}

Note: the "language" parameter is returned only when a).Language Pack has been enabled for the domain; and b). the language preference has been explicitly set for the user via API or by the user in Web UI

Get User List

Retrieves all, or a chosen subset, of users.

GET /pubapi/v2/users

Pagination Query String Parameters

Pagination of results is supported when retrieving multiple resources (e.g. users). Pagination is requested via URL query string parameters.

The following table describes the pagination query string parameters for a request:

Parameter Description Required Possible Values
startIndex The 1-based index of the first search result. No Non-negative integer that is ≥ 1
count Specifies the desired maximum number of search results per page; e.g., 50. No Must be a non-negative integer. The maximum count value supported is 100.

The following table specifies the pagination attributes returned by Egnyte in the response:

Element Description
itemsPerPage Non-negative Integer. Specifies the number of search results returned in a query response page; e.g., 50.
totalResults Non-negative Integer. Specifies the total number of results matching the query; e.g., 1000.
startIndex The 1-based index of the first result in the current set of search results; e.g., 1.

Filtering Query String Parameter

API consumers can request a subset of resources by specifying the filter URL query string parameter containing a filter expression.

The expression language that is used in the filter parameter supports references to attributes and literals. The literal values can be strings enclosed in double quotes, numbers, date times enclosed in double quotes, and Boolean values; i.e., true or false. String literals MUST be valid JSON strings.

The table below provides a brief description of the filter parameter.

Parameter Description Required Supported Attributes
filter Allows you to request a subset of users. No email, externalId , userName

The attribute name and attribute operator are case insensitive. For example, the following two expressions will evaluate to the same logical value:

filter=userName Eq "john"
filter=Username eq "john"
However, remember that query parameters, like the file paths, must be Url Encoded.  For example, if you filter for externalId attribute and the value contains the “+” character (I.e. xxx+xxx), the "+" gets encoded as "%2B" and the query would look like filter=externalId%20Eq%20xxx%2Bxxx

The filter parameter MUST contain at least one valid Boolean expression. Each expression MUST contain an attribute name followed by an attribute operator and a value. Currently this API only supports the equal (Eq or eq) operator.

Sample Response Body:

{
    "totalResults": 100,
    "itemsPerPage": 2,
    "startIndex": 1,
    "resources": [
        {
            "id": 12345678,
            "userName": "jmiller",
            "externalId": "S-1-5-21-3623811015-3361044348-30300820-1013",
            "idpUserId": "",
            "email": "john.miller@example.com",
            "emailChangePending": false,
            "name": {
                "familyName": "Miller",
                "givenName": "John",
                "formatted": "John Miller"
            },
            "active": true,
            "isServiceAccount": false,
            "language": "en-US",
            "createdDate": "2015-12-22T04:56:07.000+0000",
            "lastModificationDate": "2018-05-10T07:54:54.000+0000",
            "lastActiveDate": "2016-08-10T15:52:07.000+0000",
            "locked": false,
            "authType": "ad",
            "userType": "admin",
            "role": null,
            "userPrincipalName": "jmiller@example.com",
            "expiryDate": null,
            "deleteOnExpiry": null
        },
        {
            "id": 17654328,
            "userName": "bjensen",
            "externalId": "S-1-5-21-3623811015-3361044348-30300820-1014",
            "idpUserId": "barbara.jensen",
            "email": "bjensen@example.com",
            "emailChangePending": false,
            "name": {
                "familyName": "Jensen",
                "givenName": "Barbara",
                "formatted": "Barbara Jensen"
            },
            "active": true,
            "isServiceAccount": false,
            "language": "de-DE",
            "createdDate": "2016-06-02T01:04:59.000+0000",
            "lastModificationDate": "2018-03-12T04:21:32.000+0000",
            "lastActiveDate": "2016-08-06T19:22:34.000+0000",
            "locked": false,
            "authType": "sso",
            "userType": "power",
            "role": "Billing Admin",
            "userPrincipalName": null,
            "expiryDate": null,
            "deleteOnExpiry": null
        }
    ]
}

Create Single User

POST /pubapi/v2/users

Parameters:

Parameter Description Required Possible Values
userName The Egnyte username for the user. Yes Username must start with a letter or digit. Special characters are not supported (with the exception of periods, hyphens, and underscores).
externalId This is an immutable unique identifier provided by the API consumer. No Any plain text (e.g. S-1-5-21-3623811015-3361044348-30300820-1013)
email The email address of the user. Yes Any valid email address (e.g. admin@acme.com)
name First and last name of the user Yes Object with keys "givenName" and "familyName", e.g. {"givenName": "John", "familyName": "Smith"}
active Whether the user is active or inactive. Yes true or false
sendInvite If set to true when creating a user, an invitation email will be sent (if the user is created in active state). For authType “egnyte” will always return “True”. No true (default) or false
isServiceAccount If set to true when creating a user, the user will be created as a Service Account. No true or false (default)
language The "language" parameter is accepted only when Language Pack has been enabled for the domain. No en-US (default), fr-CA, or de-DE.
authType The authentication type for the user. Yes ad (AD), sso (SAML SSO), egnyte (Internal Egnyte)
userType The type of the user. Yes admin (Administrator), power (Power User), standard (Standard User)
role The role assigned to the user. Only applicable for Power Users. No Default or custom role name
idpUserId Only required if the user is SSO authenticated and not using default user mapping. Do not specify if user is not SSO authenticated. No This is the way the user is identified within the SAML Response from an SSO Identity Provider, i.e. the SAML Subject (e.g. jsmith)
userPrincipalName Do not specify if user is not AD authenticated. No Used to bind child authentication policies to a user when using Active Directory authentication in a multi-domain setup (e.g. jmiller@example.com)

Sample Request Body

{
    "userName": "jmiller",
    "externalId": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "email": "jmiller@example.com",
    "name": {
        "givenName": "John",
        "familyName": "Miller"
    },
    "active": true,
    "sendInvite": false,
    "language": "de-DE",
    "authType": "sso",
    "userType": "power",
    "idpUserId": "jmiller",
    "userPrincipalName": "jmiller@example.com"
}

Method-specific Response Header

Header Description Value
Location Specifies the URL location for a user, including the user ID. https://domain.egnyte.com/pubapi/v2/users/{id}

Sample Response Body

{
    "id": 12345678,
    "userName": "jmiller",
    "externalId": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "email": "jmiller@example.com",
    "emailChangePending": false,
    "name": {
        "familyName": "Miller",
        "givenName": "John",
        "formatted": "John Miller"
    },
    "active": true,
    "locked": false,
    "authType": "sso",
    "userType": "power",
    "idpUserId": "jmiller",
    "userPrincipalName": null,
    "role": "Default",
    "language": "de-DE",
    "createdDate": "2015-08-14T20:02:18.000+0000",
    "lastModificationDate": "2015-08-14T20:02:18.000+0000",
    "lastActiveDate": null,
    "expiryDate": null,
    "deleteOnExpiry": null
}

Method-specific Response Code

Header Description
409 Server refused to create a new duplicate user

Update Single User

Updates a single user. Partial updates are supported. Fields not specified in the request will not be updated.

PATCH /pubapi/v2/users/{id}

Path Parameters:

ParameterDescriptionRequiredPossible Values
id An opaque, immutable, unique identifier for the user, generated by Egnyte. This identifier is used to refer to the user in all API calls. Yes Must be the exact integer id for a given user.

Body Parameters:

Parameter Description Required Possible Values
email The email address of the user. No Any valid email address (e.g. admin@acme.com)
familyName The last name of the user. No Any plain text (e.g. John)
givenName The first name of the user. No Any plain text (e.g. Smith)
active Whether the user is active or inactive. No true or false
sendInvite The parameter cannot be the only one modified by this PATCH method, it can be set only in addition to another parameter. If set to true, an invitation email will be sent (if the user is or is set to be in the active state). No true or false
language The "language" parameter is accepted only when Language Pack has been enabled for the domain. No en-US (default), fr-CA, or de-DE.
authType The authentication type for the user. No ad (AD), sso (SAML SSO), egnyte (Internal Egnyte)
userType The type of the user. No admin (Administrator), power (Power User), standard (Standard User)
role The role assigned to the user. Only applicable for Power Users. No Default or custom role name
idpUserId Only required if the user is SSO authenticated and not using default user mapping. Do not specify if user is not SSO authenticated. No This is the way the user is identified within the SAML Response from an SSO Identity Provider, i.e. the SAML Subject (e.g. jsmith)
userPrincipalName Do not specify if user is not AD authenticated. No Used to bind child authentication policies to a user when using Active Directory authentication in a multi-domain setup (e.g. jmiller@example.com)

Sample Request Body

{
    "email": "john.miller@example.com",
    "language": "de-DE",
    "userType": "admin"
}

Method-specific Response Header:

Header Description Value
Location Specifies the URL location for a user, including the user ID. https://domain.egnyte.com/pubapi/v2/users/{id}

Sample Response Body

{
    "id": 12345678,
    "userName": "jmiller",
    "externalId": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "email": "john.miller@example.com",
    "name": {
        "familyName": "Miller",
        "givenName": "John"
    },
    "active": "true",
    "locked": "false",
    "language": "de-DE",
    "authType": "sso",
    "userType": "admin",
    "idpUserId": "jmiller"
}

Method-specific Response Code

Error Description
404 Specified user does not exist

Delete Single User

Deletes a single user.

DELETE/pubapi/v2/users/{id}

Path Parameters:

ParameterDescriptionRequiredPossible Values
id An opaque, immutable, unique identifier for the user, generated by Egnyte. This identifier is used to refer to the user in all API calls. Yes Must be the exact integer id for a given user.

Method-specific Response Code:

Error Description
404 Specified user does not exist

version 149 as of 3 years ago by Vitaly Obernikhin