User Provisioning API Getting Started
The AgilePlace User Provisioning API is a REST API for user management based on the System for Cross-Domain Identity Management (SCIM) 1.1 specification.
Common tasks supported by the API
- Add a user
- Get a user's information
- Search for users that match criteria
- Modify a user's information
- Deactivate a user
- Change a user's password
- Delete a user
Base Url
https://myaccount.leankit.com/io/scim/v1
Authentication
Two forms of authentication are supported: basic and bearer. Only administrator users are allowed to access the user provisioning API.
Basic
The username and password are base64-encoded and appended to the header of each HTTP request with basic authentication.
curl -H "Authorization: Basic <base64encodedcredentialshere>" https://myaccount.leankit.com/io/scim/v1/Users
Bearer Token
Basic authentication can be used to make a POST request to retrieve a token. That token is used for authentication in subsequent requests.
POST https://myaccount.leankit.com/io/auth/token
Example request body:
{
"description": "description for your app"
}
Example response body:
{
"id": "12345678",
"token": "longstringwiththetokenhere",
"description": "description for your app",
"createdOn": "2017-08-24T22:42:40.755Z"
}
Subsequent requests would include an Authorization header with the token:
curl -H "Authorization: Bearer <yourtokenhere>" https://myaccount.leankit.com/io/scim/v1/Users
Additional information can be found in the token management operations documentation.
Custom AgilePlace Schema
We have extended the user with a custom schema to include a number of AgilePlace specific fields. These fields are optional.
"urn:scim:schemas:extension:leankit:user:1.0": {
"licenseType": "full",
"lastAccess": "2017-08-23T20:49:43Z",
"administrator": false,
"boardCreator": false,
"dateFormat": "mm/dd/yyyy"
}
- licenseType - reserved for future use
- lastAccess - the last time the user performed an action (read only)
- administrator - assign administrator permissions to a user
- boardCreator - assign board creator permissions to a user
- dateFormat - the format requested for date display: (mm/dd/yyyy, dd/mm/yyyy, yyyy/mm/dd)
Endpoints
Service provider configuration
GET /ServiceProviderConfigs
Configuration information about the API including supported operations and authentication.
Returns
- 200 OK
Example response body:
{
"schemas": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:leankit:user:1.0"
],
"patch": {
"supported": false
},
"bulk": {
"supported": false,
"maxOperations": 0,
"maxPayloadSize": 0
},
"filter": {
"supported": true,
"maxResults": 200
},
"changePassword": {
"supported": false
},
"sort": {
"supported": true
},
"etag": {
"supported": false
},
"xmlDataFormat": {
"supported": false
},
"authenticationSchemes": [
{
"type": "oauthbearertoken",
"name": "OAuth Bearer Token",
"description": "Authentication Scheme using the OAuth Bearer Token Standard",
"specUri": "http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-01",
"primary": true
},
{
"name": "HTTP Basic",
"type": "httpbasic",
"description": "Authentication scheme using the HTTP Basic Standard",
"specUri": "https://www.ietf.org/rfc/rfc2617.txt"
}
]
}
Schemas
GET /Schemas/Users
Information about how users are modeled and which fields are supported.
Returns
- 200 OK
Example response body:
{
"id": "urn:scim:schemas:core:1.0:User",
"name": "User",
"description": "Core User",
"schema": [
"urn:scim:schemas:core:1.0",
"urn:scim:schemas:extension:leankit:user:1.0"
],
"endpoint": "/Users",
"attributes": [
{
"name": "id",
"type": "string",
"multiValued": false,
"description": "Unique identifier for the SCIM Resource as defined by the Service Provider. Each representation of the Resource MUST include a non-empty id value. This identifier MUST be unique across the Service Provider's entire set of Resources. It MUST be a stable, non-reassignable identifier that does not change when the same Resource is returned in subsequent requests. The value of the id attribute is always issued by the Service Provider and MUST never be specified by the Service Consumer. bulkId: is a reserved keyword and MUST NOT be used in the unique identifier. REQUIRED and READ-ONLY.",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": true,
"required": true,
"caseExact": false
},
{
"name": "userName",
"type": "string",
"multiValued": false,
"description": "Unique identifier for the User, typically used by the user to directly authenticate to the service provider. Often displayed to the user as their unique identifier within the system (as opposed to id or externalId, which are generally opaque and not user-friendly identifiers). Each User MUST include a non-empty userName value. This identifier MUST be unique across the Service Consumer's entire set of Users. REQUIRED.",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": false,
"required": true,
"caseExact": false
},
{
"name": "name",
"type": "complex",
"multiValued": false,
"description": "The components of the User's real name. Providers MAY return just the full name as a single string in the formatted sub-attribute, or they MAY return just the individual component attributes using the other sub-attributes, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component attributes should be combined.",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": false,
"required": true,
"caseExact": false,
"subAttributes": [
{
"name": "formatted",
"type": "string",
"multiValued": false,
"description": "The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Ms. Barbara Jane Jensen, III.).",
"readOnly": true,
"required": false,
"caseExact": false
},
{
"name": "familyName",
"type": "string",
"multiValued": false,
"description": "The family name of the User, or \"Last Name\" in most Western languages (e.g. Jensen given the full name Ms. Barbara Jane Jensen, III.).",
"readOnly": false,
"required": true,
"caseExact": false
},
{
"name": "givenName",
"type": "string",
"multiValued": false,
"description": "The given name of the User, or \"First Name\" in most Western languages (e.g. Barbara given the full name Ms. Barbara Jane Jensen, III.).",
"readOnly": false,
"required": true,
"caseExact": false
}
]
},
{
"name": "timezone",
"type": "string",
"multiValued": false,
"description": "The User's time zone in the \"Olson\" timezone database format; e.g.,\"America/Los_Angeles\".",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": false,
"required": false,
"caseExact": false
},
{
"name": "active",
"type": "boolean",
"multiValued": false,
"description": "A Boolean value indicating the User's administrative status. The definitive meaning of this attribute is determined by the Service Provider though a value of true infers the User is, for example, able to login while a value of false implies the User's account has been suspended.",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": false,
"required": false,
"caseExact": false
},
{
"name": "password",
"type": "string",
"multiValued": false,
"description": "The User's clear text password. This attribute is intended to be used as a means to specify an initial password when creating a new User or to reset an existing User's password. No accepted standards exist to convey password policies, hence Consumers should expect Service Providers to reject password values. This value MUST never be returned by a Service Provider in any form.",
"schema": "urn:scim:schemas:core:1.0",
"readOnly": false,
"required": false,
"caseExact": false
},
{
"name": "urn:scim:schemas:extension:leankit:user:1.0",
"type": "complex",
"multiValued": true,
"description": "The following SCIM extension defines attributes used in representing extended fields for Leankit users. The Leankit user extension is identified using the following URI: \"urn:scim:schemas:extension:leankit:user:1.0\".",
"schema": "urn:scim:schemas:extension:leankit:user:1.0",
"readOnly": false,
"required": false,
"caseExact": false,
"subAttributes": [
{
"name": "licenseType",
"type": "string",
"multiValued": false,
"description": "Used for future expansion",
"readOnly": false,
"required": false,
"caseExact": false,
"canonicalValues": [
"full"
]
},
{
"name": "lastAccess",
"type": "datetime",
"multiValued": false,
"description": "A datetime value indicating the last time user accessed the system.",
"readOnly": true,
"required": false,
"caseExact": false
},
{
"name": "dateFormat",
"type": "string",
"multiValued": false,
"description": "Indicates the desired date format (year, month, day) for the user. Example: \"mm/dd/yyyy\".",
"readOnly": false,
"required": false,
"caseExact": false,
"canonicalValues": [
"mm/dd/yyyy",
"dd/mm/yyyy",
"yyyy/mm/dd"
]
},
{
"name": "administrator",
"type": "boolean",
"multiValued": false,
"description": "A boolean value indicating whether or not the user is an admistrator in the system.",
"readOnly": false,
"required": false,
"caseExact": false
},
{
"name": "boardCreator",
"type": "boolean",
"multiValued": false,
"description": "A boolean value indicating whether or not the user can create boards.",
"readOnly": false,
"required": false,
"caseExact": false
}
]
}
]
}
Errors
Errors are returned in the following format:
{
"Errors": [
{
"code": 400,
"description": "Validation Failure",
"errors": {
"": [
"should have required property 'userName'"
]
}
}
]
}