ANCILE Info Pak, uLearn, & uAlign

uAlign API: Users

The Users API implements the System for Cross-domain Identity Management (SCIM) 1.1 protocol that an Identity Provider or organization can use to programmatically create, update, and delete users.

 

List

Gets members of the organization specified in the header of the API request. The response will be a list of up to the first 1,000 users as full user response. You can optionally include the startIndex and count parameters in the request. If the parameters are present, the response will start at the specified start index and return the specified number of users. The response will include the total number of members in the organization as well as the start index and number of users listed in the current response.

Route

GET /api/v4/users

Headers

  • Content-Type: application/json
  • Authorization: Bearer [token]
  • X-uAlign-Organization: [organization_uuid]

Sample Request and Response

Status: 200 OK

Response Body:

{
    "totalResults": 500,
    "itemsPerPage": 2,
    "startIndex": 1,
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "Resources": [
        full user response,
        full user response,
    ]
}

Sample Error

Status: 401 Unauthorized

Response Body:

{
  "Errors": [
    {
      "description": "Invalid authentication",
      "code": "401"
    }
  ]
}

 

Show

Gets the specified user from the organization specified in the header of the API request. The response will be a full user response.

Route

GET /api/v4/users/[user_uuid]

Headers

  • Content-Type: application/json
  • Authorization: Bearer [token]
  • X-uAlign-Organization: [organization_uuid]

Sample Request and Response

Status: 200 OK

Response Body:

      full user response

Sample Error

Status: 404 Not Found

Response Body:

{
  "Errors": [
    {
      "description": "Could not find user provided",
      "code": "404"
    }
  ]
}

 

Add

Adds a user to the organization specified in the header of the API request. The request body should be JSON with values for the new user's attributes. The response will be a full user response.

Route

POST /api/v4/users

Headers

  • Content-Type: application/json
  • Authorization: Bearer [token]
  • X-uAlign-Organization: [organization_uuid]

Sample Request and Response

Request Body:

      {
        "schemas": ["urn:scim:schemas:core:1.0"],
        "emails": [
          {
            "type": "primary",
            "value": "[user_email]"
          }
        ],
        "name": {
           "familyName": "[user_last_name]",
           "givenName": "[user_first_name]"
         },
        "userType": "[user_role]",
        "userName": "[user_username]",
        "locale": "[user_locale]",
        "timezone": "[user_time_zone]"
      }

Status: 201 Created

Response Body:

      full user response

Sample Error

Status: 409 Conflict

Response Body:

{
  "Errors": [
    {
      "description": "User already belongs to this organization",
      "code": "409"
    }
  ]
}

 

Update

Edits a user in the organization specified in the header of the API request. The request body should be JSON with values for the user's attributes. You can include one or more attributes to update. The response will be a full user response. If the organization specified in the request header does not match the authenticating organization of the user specified in the request, the user will not be modified and the response status will be HTTP 409 Conflict.

PATCH and PUT commands perform different functions in the Update endpoint.  

  • PUT performs a full update, overwriting all previously stored data with the exception of the password attribute. You must retrieve the entire Resource and PUT the desired modifications. 
  • PATCH updates only those attributes specified.  

Route

PATCH /api/v4/users/[user_uuid]
PUT /api/v4/users/[user_uuid]

Headers

  • Content-Type: application/json
  • Authorization: Bearer [token]
  • X-uAlign-Organization: [organization_uuid]

Sample Request and Response

Request Body:

      {
        "schemas": ["urn:scim:schemas:core:1.0"],
        "emails": [
          {
            "type": "primary",
            "value": "[user_email]"
          }
        ],
        "name": {
           "familyName": "[user_last_name]",
           "givenName": "[user_first_name]"
         },
        "userType": "[user_role]",
        "userName": "[user_username]",
        "locale": "[user_locale]",
        "timezone": "[user_time_zone]"
      }

Status: 200 OK

Response Body:

      full user response

Sample Error

Status: 422 Unprocessable Entity

Response Body:

{
  "Errors": [
    {
      "description": "Email has already been taken",
      "code": "422"
    }
  ]
}

 

Remove

Removes the user from the organization specified in the header of the API request. The response will be a 204 No Content and will have no body.

Route

DELETE /api/v4/users/[user_uuid]

Headers

  • Content-Type: application/json
  • Authorization: Bearer [token]
  • X-uAlign-Organization: [organization_uuid]

Sample Request and Response

Request Body:

Status: 204 No Content

Response Body:

 

Sample Error

Status: 404 Not Found

Response Body:

{
  "Errors": [
    {
      "description": "Could not find user provided",
      "code": "404"
    }
  ]
}

 

Sample Full User Response

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "id": "[user_uuid]",
    "externalId": "",
    "userName": "sample",
    "name": {
        "formatted": "sample user",
        "familyName": "sample",
        "givenName": "user",
        "middleName": "",
        "honorificPrefix": "",
        "honorificSuffix": ""
    },
    "displayName": "sample user",
    "nickName": "sample",
    "profileUrl": "http://[hostname]/users/[user_uuid_id]/edit",
    "emails": [
        {
            "value": "sample.user@email.com",
            "type": "primary"
        }
    ],
    "addresses": [
        {
            "type": "",
            "streetAddress": "",
            "locality": "",
            "region": "",
            "postalCode": "",
            "country": "",
            "formatted": "",
            "primary": ""
        }
    ],
    "phoneNumbers": [
        {
            "value": "",
            "type": ""
        }
    ],
    "ims": [
        {
            "value": "",
            "type": ""
        }
    ],
    "photos": [
        {
            "value": "",
            "type": ""
        }
    ],
    "userType": "",
    "title": "",
    "preferredLanguage": "fr",
    "locale": "fr",
    "timezone": "Eastern Time (US & Canada)",
    "active": true,
    "password": "",
    "groups": [
        {
            "value": "",
            "type": ""
        }
    ],
    "x509Certificates": [
        {
            "value": ""
        }
    ],
    "meta": {
        "created": "2014-09-26T19:45:06Z",
        "lastModified": "2014-11-03T15:45:02Z",
        "version": "",
        "location": "http://[hostname]/api/v4/users/[user_uuid]"
    },
    "organizations": [
        {
            "id": "[organization_uuid]",
            "name": "OrganizationName",
            "role": "Admin"
        }
    ]
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments