SCIM provisioning API

Overview

The SCIM (System for Cross-domain Identity Management) Provisioning API is a standard protocol for automating the provisioning and management of user identities in cloud-based applications. Proton supports this API, which allows you to create, update, delete, and manage user accounts and groups. The API is based on the SCIM 2.0 specification, which provides a common user schema and RESTful API interface for ease of integration. 

Proton supports the following identity providers:

• Okta (https://www.okta.com/(new window))
• Microsoft Entra ID

The base URL for all calls from the identity provider is: https://scim.proton.me/{tenentId}/v2/(new window). All SCIM methods are branches of this base URL.

Authentication

The token must be included in an Authorization header with a type of Bearer when calling any of the SCIM methods. This token can be generated and replaced in the Single-sign-on > SCIM automatic provisioning section. Click on the “Generate new token” button and copy the generated token.

For example:

GET /Users?count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Users

Core Attributes

id	A unique identifier for a SCIM resource, such as a user, that is defined by Proton.
userName (required)	A unique identifier for the user. Here we use email as userName.
active	A boolean indicating if the user is active. The default is true.

Operations

Retrieve a paginated list of all users

Request

GET /Users?count=1 Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Response

{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:ListResponse"
	],
	"totalResults": 1,
	"itemsPerPage": 1,
	"startIndex": 1,
	"Resources": [
		{
			"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
			"userName": "test@sso.protonhub.org",
			"active": true
		}
	]
}

Create a new user

Request

POST /UsersHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Response

{
	"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	"id": "avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
	"userName": "test@sso.protonhub.org",
	"active": true,
	"meta": {
		"resourceType": "User",
		"created": "2024-07-25T04:39:27Z",
		"lastModified": "2024-07-25T04:39:27Z",
		"location": "https://scim.proton.me/{tenent-id}/v2/Users/avveKyJZ_cCkULxxxZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
		"version": "1"
	}
}

Retrieve a single user

Request

GET /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Response

{
	"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
	"id": "avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==",
	"userName": "test@sso.protonhub.org",
	"active": true,
	"meta": {
		"resourceType": "User",
		"created": "2024-07-24T06:22:20Z",
		"lastModified": "2024-07-24T06:22:20Z",
		"location": "https://scim.proton.me/{tenentId}/v2/Users/avveKyJZ_cCkUL1iBZj4_U8j1IwqaGkcso02I6bDFoyrfJSqqXLS3FToNOiwP1tNwBaaraqfKVE993xaVcYSxQ==",
		"version": "1"
	},
	"externalId": "00uganxwluxxxxxxxxxx"
}

Delete a user

Request

DELETE /Users/avveKyJZ_cCkUL1iBZj4_U8j1IxxxGkcso02I6xDFoyrfJSxxXLS3FToNOiwP1tNwBaaraqfKVExx3xaVcYSxQ==Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Groups

Core Attributes

id	A unique identifier for a SCIM resource, such as a user, that is defined by Proton.
displayName	Name for the group.
members	A list of group members.

Operations

Get list of groups

Request

GET /Groups?startIndex=1&count=10Host: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Response

{
	"schemas": [
		"urn:ietf:params:scim:api:messages:2.0:ListResponse"
	],
	"totalResults": 0,
	"itemsPerPage": 100,
	"startIndex": 1,
	"Resources": [
		{
			"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
			"displayName": "Admins",
			"members": [
				{
					"value": "2819c223-7f76-453a-919d-413861904646",
					"display": "John Doe"
				}
			],
			"meta": {
				"resourceType": "Group",
				"created": "2024-07-25T05:10:22Z",
				"lastModified": "2024-07-25T05:10:22Z",
				"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
			}
		}
	]
}

Retrieve a group’s details by their unique ID

Request

GET /Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54eHost: scim.proton.meAccept: application/scim+jsonAuthorization: Bearer {token}

Response

{
	"id": "d27f32f6-1e03-4e34-b5b5-9b89c11ed54e",
	"displayName": "Admins",
	"members": [{ "value": "2819c223-7f76-453a-919d-xxxxxxxxxxxx", "display": "John Doe" }],
	"meta": {
		"resourceType": "Group",
		"created": "2024-07-25T05:10:22Z",
		"lastModified": "2024-07-25T05:10:22Z",
		"location": "https://scim.proton.me/{tenentId}/v2/Groups/d27f32f6-1e03-4e34-b5b5-9b89c11ed54e"
	}
}

Error Handling

The responses are formatted following RFC-7644 section 3.12(new window) which are delivered with an HTTP status code indicating the nature of the error and a response body providing more details.

Error Response

{
	"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
	"detail": "UserName is already taken",
	"status": "400"
}

The most common errors

• 400 Bad Request: The request was invalid or cannot be otherwise served.
• 404 Not Found: The requested resource could not be found.
• 409 Conflict: The request could not be completed due to a conflict with the current state of the target resource.
  • uniqueness: A unique attribute value already exists in the system.
• 500 Internal Server Error: An error occurred on the server side.