Proton VPN homepage
ProtonVPN

SCIM provisioning API

Reading
2 mins
Category
Proton VPN for Business

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:

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

idA 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.
activeA 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

idA unique identifier for a SCIM resource, such as a user, that is defined by Proton.
displayNameName for the group.
membersA 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.

Didn’t find what you were looking for?

General contactcontact@proton.me
Media contactmedia@proton.me
Legal contactlegal@proton.me
Partnerships contactpartners@proton.me