User Provisioning

You can create users in MyGuide using User Provisioning APIs. MyGuide supports the following methods based on the authorization token type.

Basic Auth
SCIM v1 using API token (This method supports SCIM compliant APIs)
JWT token

1. Steps for enabling user provisioning with Basic Auth

Click on the "User Provisioning" button on the organization's view page.
Select "Basic Token" under the provision method.
It is necessary to provide the email ID that the user wishes to use for user provisioning. The email ID must belong to the organization and must have the owner's privilege.
Click on "Save" to update the configuration.

Note: Create a base64 encoded string of email and password which are separated by a colon. eg. test@edcast.com:password. This base64 encoded string is used as it is in the Authorization header.

API Details

Name	URL	Method	Headers	Parameters or Body	Sample POST and the PUT request body
Create User	https://api-v3.guideme.io/v3/user/provisioning/basic_auth	POST	Content-Type: application/json Authorization: Basic {BASIC_TOKEN}	first_name - required last_name - required email_id - required profile - optional	{ "first_name": "Developer" "last_name": "Edcast", "email_id": "dev@edcast.com", "profile" : "{\"department\": \"IT\", \"role\": \"Developer\"}" }
Update User	https://api-v3.guideme.io/v3/user/provisioning/basic_auth	PUT	Content-Type: application/json Authorization:Basic {BASIC_TOKEN}	user_id - required first_name: required last_name - required email_id - required active - required profile - optional	{ "user_id": 1234 "first_name": "Developer" "last_name": "Edcast", "email_id": "dev@edcast.com", "active": true "profile" : "{\"department\": \"IT\", \"role\": \"Developer\"}" }
GET User	https://api-v3.guideme.io/v3/user/provisioning/basic_auth	GET	Content-Type: application/json Authorization:Basic {BASIC_TOKEN}	user_id - required
Delete User	https://api-v3.guideme.io/v3/user/provisioning/basic_auth	DELETE	Content-Type: application/json Authorization:Basic {BASIC_TOKEN}	user_id - required

Status codes and error messages

Condition	API	Http status code	Custom status Code	Message
If Authorization Header Invalid	Create User, Delete User, Update user, Get Users	401	2034	Invalid/Empty/Expired Header [Authorization]
If user which we are trying to create already exists	Create User	200	3003	User already exists
If user_id which passed to an API is invalid	Update User, Delete User, Get User	200	2005	User ID invalid. Please try again

2. Steps for enabling user provisioning SCIM v1 using API token.

Click on the "user provisioning" button on the organisation's view page.
Select "API Token" under the provision method and click on "Generate token(s)".
A pop-up message will appear on the screen with the API Token.

Note: These tokens must be copied and stored securely before closing the pop-up message. It is not possible to view or edit the tokens again and can only be regenerated which will revoke access of the existing tokens.

Note: The API token provided under the "user provisioning" section can be used as-is in the authorization header.

{
    "schemas": ["urn:scim:schemas:core:1.0", "urn:ietf:params:scim:schemas:extension:myGuide:1.0:User"],
    "userName": "{$parameters.scimusername}",
    "name": {
        "givenName": "{$user.firstname}",
        "familyName": "{$user.lastname}",
        "formatted": "{$user.display_name}"
    },
    "urn:ietf:params:scim:schemas:extension:myGuide:1.0:User": {
        "key1": "value1",
        "key2": "value2"
    }
}

Fields	Description
schemas	This shows the schemas supported.
urn:ietf:params:scim:schemas:extension:myGuide:1.0:User	This is myGuide
userName	Email ID of the user
name.givenName	First Name of the user
name.familyName	Last Name of the user

API Details

Name	URL	Method	Headers	Parameter/Body
Create User	https://api-v3.guideme.io/scim/v1/provisioning/users	POST	Content-Type: application/json Authorization:{API_TOKEN}	Body as per above explained SCIM template
Update User	https://api-v3.guideme.io/scim/v1/provisioning/users/{id}	PUT	Content-Type: application/json Authorization:{API_TOKEN}	Body as per above explained SCIM template
Get User by Id	https://api-v3.guideme.io/scim/v1/provisioning/users/{id}	GET	Content-Type: application/json Authorization:{API_TOKEN}	user_id
Get User by the filter	https://api-v3.guideme.io/scim/v1/provisioning/users	GET	Content-Type: application/json Authorization:{API_TOKEN}	filter=userName eq
Delete User	https://api-v3.guideme.io/scim/v1/provisioning/users/{id}	DELETE	Content-Type: application/json Authorization:{API_TOKEN}	user_id
Activate/suspend User	https://api-v3.guideme.io/scim/v1/provisioning/users/{id}	PATCH	Content-Type: application/json Authorization:{API_TOKEN}	user_id

Note: All the APIs mentioned for API token-based user provisioning is SCIM compliant. Currently, we support the SCIM core schema 1.1. The basic schema template required for successful user provisioning using SCIM is shown below.

Status codes and error messages

Condition	API	Http status code	Custom status Code	Message
If Authorization Header Invalid	Create User, Delete User, Update user, Get Users	401	2034	Invalid/Empty/Expired Header [Authorization]
If any invalid parameter supplied	Create User, Update User	400	2000	The required parameter is missing
If user which we are trying to create already exists	Create User	409	3003	User already exists
If user_id which passed to an API not exists	Update User, Delete User, Get User	404	3041	The specified resource is not available.

3. Steps for enabling user provisioning with JWT TOKEN.

Click on the "user provisioning" button on the organization's view page.
Select "JWT Token" under the provision method and click on "Generate token(s)".
A pop-up message will appear on the screen with the API Key and API secret.

Note: This key and Secret is used to generate JWT token which is used in the authorisation header.

Key	Value	Description
Algorithm	HS256	This is default JWT algorithm
Payload	{ api_key:{{KEY}}, expire:{{EXPIRY_TIME}} }	{{KEY}}should be the value of API Key generated in MyGuide Admin panel. {{EXPIRY_TIME}} should be UNIX timestamp (UNIX epoch) format and greater than the current timestamp.
Secret	{{SCERET}}	{{SCERET}} should be value of API Secret generated in MyGuide Admin Panel.

API Details

Name	URL	Method	Header	Parameters/Body
Create User	https://api-v3.guideme.io/v3/user/provisioning/jwt	POST	Content-Type: application/json Authorization: {JWT_TOKEN}	first_name - required last_name - required email_id - required profile - optional
Update User	https://api-v3.guideme.io/v3/user/provisioning/jwt	PUT	Content-Type: application/json Authorization: {JWT_TOKEN}	user_id - required first_name: required last_name - required email_id - required active - required profile - optional
Get user	https://api-v3.guideme.io/v3/user/provisioning/jwt	GET	Content-Type: application/json Authorization: {JWT_TOKEN}	user_id
Delete User	https://api-v3.guideme.io/v3/user/provisioning/jwt	DELETE	Content-Type: application/json Authorization: {JWT_TOKEN}	user_id

Status codes and error messages

Condition	API	Http status code	Custom status Code	Message
If Authorization Header Invalid	Create User, Delete User, Update user, Get Users	401	2034	Invalid/Empty/Expired Header [Authorization]
If Authorization Header Invalid	Create User	200	3003	User already exists
If user_id which passed to an API is invalid	Update User, Delete User, Get User	200	2005	User ID invalid. Please try again

Last Updated: 2020-08-10 3:38pm. (GMT)

Web Services (APIs)