SCIM
📘
Accessing SCIM endpoints
OnlyService Accounts inEnterprise Domains can access SCIM endpoints.
Asana supportsSCIM 2.0 operations athttps://app.asana.com/api/1.0/scim. Okta providesdocumentation 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 ifactive=false. |
PATCH | /Users/:id | Add / update attributes for a user. Deprovision user (zombify) in Asana ifactive=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-emptyuserName 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 forview only domains. |
name | complex | The user's name. |
name.givenName | string | Unsupported forPATCH request, usename.formatted. |
name.familyName | string | Unsupported forPATCH request, usename.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 anorganizational construct, and is distinct from theAsana 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 Asanateams.
| 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 ContentUpdated 4 months ago