# SCIM Provisioning API

### This documentation is to support our existing identity provider integrations

The following endpoints are not meant for self-serve use. See here for our [supported identity provider integrations](/content/docs/identity-providers/index.html).

## Overview

Twingate supports automatic user provisioning via [SCIM 2.0](http://www.simplecloud.info/). This allows seamless integration with your organization’s existing identity provider solution.

## SCIM configuration

### Endpoints

The base URL for SCIM endpoints is `https://{network}.twingate.com/api/scim/v2/` where `{network}` is your Twingate network name. For example, if your network name is `autoco`, the base URL for your SCIM endpoints is `https://autoco.twingate.com/api/scim/v2/` (`v2` designates that we support SCIM version 2.0).

### Authorization

A long-lived bearer token is required to access any SCIM endpoints. The token must be included in the `Authorization` header with a `Bearer` type. For example:

```text
GET /Users?count=100
Host: twingate.com
Accept: application/scim+json
Authorization: Bearer h480dj...s93hd8
```

This token can be created and replaced in the Twingate Admin console. Only the most recently generated token is valid at any point of time.

## Users

### Attributes

| Twingate User | SCIM Attribute                  | Required? | Unique? | Attribute Type |
|---------------|---------------------------------|-----------|---------|----------------|
| Twingate ID  | `id`                            | True      | True    | Singular        |
| Origin ID    | `externalId`                   | True      | True    | Singular        |
| Email         | `emails[primary eq true]`      | False     | False   | Multi-valued    |
| First name   | `name.givenName`               | False     | False   | Singular        |
| Last name    | `name.lastName`                | False     | False   | Singular        |
| Active       | `active`                        | False     | False   | Singular        |
| Username     | `userName`                     | True      | True    | Singular        |

- Twingate only stores one email value from the SCIM `emails` attribute’s multi-values. We looks for the email with `primary=true` or `type="work"`.

### Operations

- `GET /Users` \- to search and filter users. Pagination is supported.
- `POST /Users` \- to create a new user.
- Operations on a single user. The `{id}` is Twingate user ID that is returned in the SCIM `id` field of a user response.
  - `GET /Users/{id}` \- to retrieve a single user.
  - `PUT /Users/{id}` \- to replace a single user.
  - `PATCH /Users/{id}` \- to modify a single user.
  - `DELETE /Users/{id}` \- to delete a single user. This deletes the user in Twingate.

## Groups

### Attributes

| Twingate Group | SCIM Attribute | Required? | Unique? | Attribute Type |
|----------------|----------------|-----------|---------|----------------|
| Group name     | `displayName` | True      | False   | Singular        |
| Members        | `members`     | False     | False   | Multi-valued    |
| Twingate ID    | `id`          | True      | True    | Singular        |

### Operations

- `GET /Groups` \- to search and filter groups. Pagination is supported.
- `POST /Groups` \- to create a new group.
- Operations on a single group. The `{id}` is Twingate group ID that is returned in the SCIM `id` field of a group response.
  - `GET /Groups/{group-id}` \- to retrieve a single group.
  - `PUT /Groups/{group-id}` \- to replace a single group.
  - `PATCH /Groups/{group-id}` \- to modify a single group.
  - `DELETE /Groups/{group-id}` \- to delete a single group. This deletes the group in Twingate.

## Service Provider Configuration

_Coming soon_

## Miscellaneous

- SCIM endpoints support both `application/scim+json` (as specified in [RFC-7644 section 8.1](https://tools.ietf.org/html/rfc7644#section-8.1)) and `application/json` content types.
- Error status and responses are formatted following [RFC-7644 section 3.12](https://tools.ietf.org/html/rfc7644#section-3.12).
- Requests are rate-limited to 25 requests per second per Twingate account.

## Limitations

Twingate currently doesn’t support the following endpoints and operations:

- `/.search` endpoint for querying resources using `POST` ( [RFC-7644 section 3.4.3](https://tools.ietf.org/html/rfc7644#section-3.4.3))
- `/Bulk` endpoint for bulk operations ( [RFC-7644 section 3.7](https://tools.ietf.org/html/rfc7644#section-3.7))
- `/Me` endpoint ( [RFC-7644 section 3.11](https://tools.ietf.org/html/rfc7644#section-3.11))
- Sorting for filtering queries as specified in [RFC-7644 section 3.4.2.3](https://tools.ietf.org/html/rfc7644#section-3.4.2.3) is not supported.
- `attributes` and `excludedAttributes` query params as specified in RFC-7644 [section 3.4.2.5](https://tools.ietf.org/html/rfc7644#section-3.4.2.5) and [section 3.9](https://tools.ietf.org/html/rfc7644#section-3.9) are not supported.

Last updated 5 months ago