SCIM
Accessing SCIM endpoints
Only Service Accounts in Enterprise Domains can access SCIM endpoints.
Asana supports SCIM 2.0 operations at https://app.asana.com/api/1.0/scim
. Okta provides documentation for understanding SCIM.
Service provider configuration endpoints
HTTP method | API endpoint | Asana behavior |
---|---|---|
GET | /ServiceProviderConfig | Read-only meta information. |
GET | /ResourceTypes | Read-only meta information. |
GET | /Schemas | Read-only meta information. |
User endpoints
HTTP method | API endpoint | Asana behavior |
---|---|---|
GET | /Users | Return full list of users in the domain. Does not return Asana guest users. The accepted query parameters are: 1. filter for userName . |
GET | /Users/:id | Return specific user in the domain. Does not return Asana guest users. |
POST | /Users | Create a new user if the User does not exist. |
PUT | /Users/:id | Update / remove attributes for a User. Deprovision user (zombify) in Asana if active=false . |
PATCH | /Users/:id | Add / update attributes for a user. Deprovision user (zombify) in Asana if active=false . |
DELETE | /Users/:id | Deprovision user (zombify) in Asana. |
Accepted attributes
Attribute | Type | Info |
---|---|---|
userName | string | Unique identifier for the user, typically used by the user to directly authenticate to the service provider. Each user MUST include a non-empty userName value, and it must be an email address. Required. |
userType | string | The type of Asana license to assign to the user (e.g., "enterprise" or "view only"). Note: This attribute is currently only returned/accepted for view only domains. |
name | complex | The user's name. |
name.givenName | string | Unsupported for PATCH request, use name.formatted . |
name.familyName | string | Unsupported for PATCH request, use name.formatted . |
name.formatted | string | The full name of the user. |
emails | multi-valued complex | Email addresses for the user. |
email.value | string | Email address for the user. |
email.primary | string | Whether this email address is the preferred email address for this user. true may only appear once for this attribute. |
active | boolean | Indicates whether the user's account is active in Asana. |
title | string | The user's title, such as "Vice President". |
preferredLanguage | string | The user's preferred language. Used for selecting the localized User interface. |
addresses | multi-valued complex | The user’s address. |
address.country | string | The user’s country. |
address.region | string | The user’s region. |
address.locality | string | The user’s city. |
phoneNumbers | multi-valued complex | The user’s phone. |
phoneNumber.value | string | The user’s phone number value. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User" | complex | The Enterprise User Schema Extension attribute. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.department" | string | The department the user belongs to. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.costCenter" | string | The cost center user belongs to. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.organization" | string | The organization user belongs to. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.division" | string | This metadata field indicates which division that the user belongs to. Note: In this context, division is an organizational construct, and is distinct from the Asana division concept. As such, this metadata can be used to help reflect organizational structure in Asana (e.g., division, organization, department, cost center, etc.). |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.employeeNumber" | string | A string identifier, typically numeric or alphanumeric, assigned to a person. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.manager" | complex | The user’s manager. |
"urn:ietf:params:scim:<br>schemas:extension:enterprise:<br>2.0:User.manager.value" | string | The user’s manager’s user ID. |
Examples
Request: GET https://app.asana.com/api/1.0/scim/Users?filter=userName eq "[email protected]"
Response: 200 OK
{
"Resources": [
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "[email protected]",
"emails": [
{
"value": "[email protected]",
"primary": true,
"type": "work"
}
],
"active": true,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"title": "Software Engineer",
"addresses": [
{
"locality": "Vancouver",
"region": "BC",
"country": "CA",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"value": "111-111-1111",
"type": "work",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D",
"costCenter": "CC_ID",
"organization": "Asana",
"division": "Product",
"employeeNumber": "ID1",
"manager": {
"value": "2"
}
},
"userType": "enterprise"
}
],
"totalResults": 1,
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}
Request: POST https://app.asana.com/api/1.0/scim/Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "[email protected]",
"name": {
"formatted": "John Smith"
},
"emails": [
{
"primary": true,
"value": "[email protected]"
}
],
"active": true,
"title": "Software Engineer",
"preferredLanguage": "en",
"addresses": [
{
"locality": "Vancouver",
"region": "BC",
"country": "CA"
}
],
"phoneNumbers": [
{
"value": "111-111-1111"
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D",
"costCenter": "CC_ID",
"organization": "Asana",
"division": "Product",
"employeeNumber": "ID1",
"manager": {
"value": "2"
}
},
"userType": "enterprise"
}
Response: 201 Created
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "[email protected]",
"emails": [
{
"value": "[email protected]",
"primary": true,
"type": "work"
}
],
"active": true,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"title": "Software Engineer",
"preferredLanguage": "en",
"addresses": [
{
"locality": "Vancouver",
"region": "BC",
"country": "CA",
"type": "work",
"primary": true
}
],
"phoneNumbers": [
{
"value": "111-111-1111",
"type": "work",
"primary": true
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D",
"costCenter": "CC_ID",
"organization": "Asana",
"division": "Product",
"employeeNumber": "ID1",
"manager": {
"value": "2"
}
},
"userType": "enterprise"
}
Request: PATCH https://app.asana.com/api/1.0/scim/Users/1
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "replace",
"value": {
"title": "Senior Software Engineer"
}
}
]
}
Response: 200 OK
{
"id": "1",
"name": {
"familyName": "John",
"givenName": "Smith",
"formatted": "John Smith"
},
"userName": "[email protected]",
"emails": [
{
"primary": true,
"value": "[email protected]",
"type": "work"
}
],
"active": true,
"preferredLanguage": "en",
"title": "Senior Software Engineer",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"department": "R&D"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userType": "enterprise"
}
Group endpoints
SCIM Groups are equivalent to Asana teams.
HTTP method | API endpoint | Asana behavior |
---|---|---|
GET | /Groups | Return full list of team in the domain, including private team. The accepted query parameters are: 1. filter for displayName . |
GET | /Groups/:id | Return a specific team in the domain. |
POST | /Groups | Create a new team. |
PUT | /Groups/:id | Replace the team's attributes. |
PATCH | /Groups/:id | Update the team's attributes. |
Accepted attributes
Attribute | Type | Info |
---|---|---|
displayName | string | Unique identifier for the team. Required. |
members | multi-valued complex | The members of the team. |
members.value | string | The team member's user ID. |
Examples
Request: GET https://app.asana.com/api/1.0/scim/Groups?filter=displayName eq "Marketing"
Response: 200 OK
{
"Resources": [
{
"id": "1",
"displayName": "Marketing",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group"
}
}
],
"totalResults": 1,
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
]
}
Request: POST https://app.asana.com/api/1.0/scim/Groups
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Marketing",
"members": [
{"value": "1"},
{"value": "2"}
]
}
Response: 201 Created
{
"id": 1,
"displayName": "Marketing",
"members": [
{"value": "1"},
{"value": "2"}
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group"
}
}
Request: PATCH https://app.asana.com/api/1.0/scim/Groups/1
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": "3"
}
]
}
]
}
Response: 204 No Content
Updated 10 days ago