1. Help Center
  2. Integrations
  3. Security and sign-on integrations

Enabling SCIM

Marq offer user provisioning/deprovisioning and group management via CRUD operations against the users and groups on an enterprise account via our SCIM API. To access the API, you must follow the steps below.

For a more detailed overview of SCIM, see Simple Cloud.

Enabling SCIM

  1. Have an Enterprise subscription for Marq.
  2. Enable automatic team upgrades (Team > Licensing, requires a role of Account Owner or Billing Admin).
  3. Ensure SCIM has been enabled for your account (contact support for this).
  4. Generate a SCIM bearer token (Team > App Integration > SCIM). This token is used to authenticate your requests.
  5. Add the bearer token to your SCIM provider. Instructions for some are listed below:
    1. Okta
    2. OneLogin
    3. Azure

SCIM Endpoints

All Marq SCIM endpoints start with the Marq base URL, which can be obtained on the same page as the SCIM bearer token (Team > App Integrations > SCIM):

Bearer Token Authorization

Authorization is provided by using HTTP Authorization header, formed as such (using your own bearer token instead of the italicized example token shown):

Authorization: Bearer 1502c55ad68b4f3acdc969a7179a1313

Users


User Resource

{
"id": string,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:marq:1.0:User",
],
"userName": string,
"name": {
"formatted": string, // givenName + " " + familyName
"givenName": string,
"familyName": string
},
"displayName": string,
"emails": [{
"value": string, // email address
"primary": boolean
}],
"active": boolean,
"urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
"canEdit": boolean,
"addOns": [string]
},
"meta": {
"resourceType": "User",
"created": string, // ISO8601 DateTime
"lastModified": string, // ISO8601 DateTime
"version": string,
"location": string // URI of user
},
"roles": [string]
}
  • “id” will be of the form “marq-1234” with 1234 being the ID of the Marq user

  • userName/displayName is usually the email address of the user

  • canEdit is the license status of the user

  • Marq users also have the following which contains the user’s smart fields:

"urn:ietf:params:scim:schemas:extension:marq:1.0:UserFields":{
"website":"marq.com",
"fullName":"John Doe",
"address":"1324 Street\nSan Francisco, CA 94014",
"title":"Engineer",
"workPhone":"(888) 705-4096",
"company":"Marq",
"cellPhone":"(888) 705-4096",
"logo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
"logo_1":"https://example.com/image_1.png",
"secondaryLogo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
"secondaryLogo_1":"https://example.com/image_1.png",
"tertiaryLogo":"https://dogtime.com/assets/uploads/2018/10/puppies-cover.jpg",
"tertiaryLogo_1":"https://example.com/image_1.png",
  • For logos, it must be either "logo" for the key or "logo_" as a prefix for the key. For profile images, it is "profileImage" or a "profileImage_" prefix.
    • If you want to use the secondary and tertiary profile image, use "secondaryProfileImage" and "tertiaryProfileImage". 
     "logo_withAName":"https://example.com/image_2.png"
},
  • If you are in real estate and your agents have a license number tied to their property listings, you can use "agentNumber":
     "agentNumber": "00000000",
},
  • If you are connecting to Xpressdocs or your own printer, you will need to add the "User ID at Printer Vendor" and "Office ID at Print Vendor".
"urn:ietf:params:scim:schemas:extension:lucid:1.0:User": {

"userIdAtPrintVendor": "00000000",

"officeIdAtPrintVendor": "00000000",

"billingCode": "00000000",
}

 


 

GET All Users

Get all users on an account.

URL - /Users

Optional Parameters

  • startIndex (number): index of first user in the list to return (1 indexed)

  • count (number): quantity of users to return from this request

  • filter (string): See SCIM spec and optimization details below.

Filtering

  • The only operator currently supported is “eq”

  • While filtering should technically work on every attribute of a user, it is a very slow process for non-optimized attributes. Filter only on the following optimized attributes whenever possible:

    • email / emails.value / workemail

    • username / displayname

    • externalid

    • canedit / urn:ietf:params:scim:schemas:extension:marq:1.0:user.canedit / urn:marq:schemas:1.0:user.canedit

  • Example : /Users?filter=email eq someEmail@example.com

  • Example : /Users?filter=urn:ietf:params:scim:schemas:extension:marq:1.0:user.canedit  eq true

Response Body

{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": number,
"startIndex": number,
"itemsPerPage": number,
"Resources": [UserResource]
}

GET User

Get a specific user on the account

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Response Body

See UserResource

 


POST User

Create a new user

URL - /Users

Request Body

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": string,
"name": {
"formatted": string (optional),
"familyName": string (optional),
"givenName": string (optional)
},
"displayName": string (optional),
"password": string (optional), // length must be at least 6 characters
"emails": [{
"value": string, // email address
"type": string (optional),
"primary": boolean (optional)
}],
"active": boolean (optional),
"id": string (optional),
"urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
"canEdit": boolean (optional),
"addOns": [string] (optional) // valid addOns: “press-for-sales”
} (optional),
"roles": [string] (optional)
}
  • Many parameters are marked as optional because they are not used in Marq’s system and will be ignored

  • password must be at least 6 characters in length (Marq password requirement)

  • Marq roles (“Team Admin”, “Billing Admin”, etc) that are listed in the roles field will be added to the user in Marq

  • addOns that are listed will give a user an addon license of the specified type

Response Body

See UserResource

 


PUT User

Modify an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Request Body

  {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": string,
"name": {
"formatted": string (optional),
"familyName": string (optional),
"givenName": string (optional)
},
"displayName": string (optional),
"password": string (optional), // length must be at least 6 characters
"emails": [{
"value": string, // email address
"type": string (optional),
"primary": boolean (optional)
}],
"active": boolean (optional),
"id": string (optional),
"urn:ietf:params:scim:schemas:extension:marq:1.0:User": {
"canEdit": boolean (optional),
"addOns": [string] (optional) // valid addOns: “press-for-sales”
} (optional),
"roles": [string] (optional)
}
  • Will fail if attempting to update a user’s username or ID to a username or ID that already exist

  • All notes from POST User also apply

  • addOns will grant or leave any add-on licenses that are specified, and remove any licenses that the user has that are not specified. An empty list will remove all add-on licenses from the user. If no addOns field is specified, no change will be made to the user’s licenses

Response Body

See UserResource

 


PATCH User

Modify an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Request Body

 {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"],
"Operations": [
{
"op": string, // can be add, remove, or replace
"path": string (optional),
"value": JSON (optional) // object/array to be added/replaced
}
]
}

Response Body

See UserResource 


DELETE User

Delete an existing user

URL - /Users/userIdString

userIdString: of the form “marq-1234” where 1234 is the ID of the Marq user

Response

  • 204 No Content if delete was successful

  • 404 Not Found if the user was not found

Groups


Group Resource

  {
"id": string,
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": string,
"members": [{
"value": string, // id of group member
"$ref": string, // URI of group member
"display": string
}],
"meta": {
"resourceType": "Group",
"created": string, // ISO8601 DateTime
"lastModified": string, // ISO8601 DateTime
"version": string,
"location": string // URI of group
}
}
  • “id” will be of the form “marq-group-1234” with 1234 being the ID of the Marq group


GET All Groups

Get all groups on an account.

URL - /Groups

Optional Parameters

  • startIndex (number): index of first group in the list to return (1 indexed)

  • count (number): quantity of groups to return from this request

  • filter (string): See SCIM spec (currently only the eq operator is supported)

Response Body

  {
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": number,
"startIndex": number,
"itemsPerPage": number,
"Resources": [GroupResource]
}

GET Group

Get a specific group on the account

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Response Body

See GroupResource

 


POST Group

Create a new group

URL - /Groups

Request Body

 {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": string,
"members": [{
"value": string, // id of group member
"$ref": string (optional), // URI of group member
"display": string (optional)
}]
}
  • Parameters that are marked optional are ignored since attributes of a single member are immutable when using the Groups API

Response Body

See GroupResource

 


PUT Group

Modify an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Request Body

  {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": string,
"members": [{
"value": string, //id of group member
"$ref": string (optional), //URI of group member
"display": string (optional)
}]
}

Response Body

See GroupResource

 


PATCH Group

Modify an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Request Body

 {
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:PatchOp"],
"Operations": [
{
"op": string, // can be add, remove, or replace
"path": string (optional),
"value": JSON (optional) // object/array to be added/replaced
}
]
}

Response Body

See GroupResource


DELETE Group

Delete an existing group

URL - /Groups/groupIdString

groupIdString: of the form “marq-group-1234” where 1234 is the ID of the Marq group

Response

  • 204 No Content if delete was successful

  • 404 Not Found if the group was not found