Was this page helpful?

User Management API

Note: The User Management API is only available to Enterprise customers whose subscription plan includes this feature. Talk to your customer success manager to learn more.

Introduction

Contentful's User Management API helps organizations programatically manage their organizations, organization memberships and space memberships.

Organization Memberships and Users

Organization users are the Contentful users who are current members of your organization. Organization memberships represent the relationship between a single Contentful user and your organization. In other words, they are the data object that define explicitly who is a member of your organization.

The user and membership endpoints in the following section allow organization owners and admins to:

  • View details about users in the organization, including personal information like name and email address as well as information specific to their organization membership, like their role.
  • Add (via invitation) and remove users from the organization.
  • Make changes to a user's organization membership; for example, to change the user's role.

Space Membership

Space memberships represent the relationship between a single Contentful user and a space within your organization. In other words, they are the data object that defines explicitly who is a member of which space.

Disclaimer

This feature is currently in alpha and is under active development. It may undergo some major changes, hence it is not recommended to use in production.

Share your thoughts, ideas, and feedback using the feedback button, or connect with us on our #user-management-api Slack community channel.

Give feedback

Authentication

  • A valid Content Management API token.

Pagination

Contentful returns collections of resources in a wrapper object that contains extra information useful for paginating over large result sets.

Example Usage

Example query string:

limit=25&skip=2

Example response:

{
  "sys": { "type": "Array" },
  "skip": 0,
  "limit": 100,
  "total": 1256,
  "items": [ /* 100 individual resources */ ]
}

Request Parameters

Parameter Description
skip Specify an offset (as an integer) to paginate through results. The first "page" is skip=0.
limit Specify (as an integer) the maximum number of results. The maximum number of entries returned by the API is 1000.

Response Attributes

Paginated collections include a few additional top-level attributes related to pagination:

Attrbiute Description
skip The offset specified in the request
limit The limit specified in the request (or the default for the collection, if none specified)
total The total number (i.e. unpaginated) of resources in the collection specified by the query
items The resources for the current request, as scoped by any pagination or filter parameters

Sorting Results

You can use the order parameter when paging through larger result sets to keep ordering predictable.

Example Usage

order=name,-sys.createdAt
  • Results are returned in ascending order for the specified attributes(s).
  • Use - in front of the attribute to specify descending order.
  • Separate multiple sort attributes with a comma. Sort fields are applied in the order specified.
  • Attributes are identified by their path (e.g. sys.user.firstName).
  • See endpoint documentation for a list of which order attributes are supported for that endpoint.

You can use the include parameter to include linked resources in your response. This allows you to avoid making additional requests to fetch related resources.

Example Usage

include=author,sys.createdBy

As a more detailed explanation, imagine the following API request and response:

Request:

GET /books

Response:

{
  ...
  "items": [{
    "title": "My Book",
    "author": {
      "sys": {
        "id": "author-id",
        "type": "Link",
        "linkType": "User"
      }
    },
    "sys": {
      "updatedBy": {
        "id": "some-user-id",
        "type": "Link",
        "linkType": "User"
      }
    }
  }]
}

To fetch the linked users referenced in author and sys.updatedBy, you need to make subsequent API calls.

Using the include parameter you can request the linked users to be returned in the response:

Request:

GET /books?include=author,sys.updatedBy

Response:

{
  ...
  "items": [{
    "title": "My Book",
    "author": {
      "sys": {
        "id": "author-id",
        "type": "Link",
        "linkType": "User"
      }
    },
    "sys": {
      "updatedBy": {
        "id": "some-user-id",
        "type": "Link",
        "linkType": "User"
      }
    }
  }
 ],
  "includes": {
    "User": [
      {
        "firstName": "Jane",
        "lastName": "Smith",
        "sys": {
          "id": "author-id",
          "type": "User"
        }
      },
      {
        "firstName": "Mary",
        "lastName": "Jones",
        "sys": {
          "id": "some-user-id",
          "type": "User"
        }
      },
    ]
  }
}

Additional Notes

  • Linked resources are returned in the includes attribute of the response body, organized by type. In the example above, the included objects are users and are thus returned in the "User" attribute.
  • Only resources related to the current result set are included in the response. For example, if you are paginating through a list of results, include only includes related resources for that page (not the entire result set).
  • Resources to include are identified by their path in the query string.
  • See endpoint documentation for a list of which include fields are supported.

Searching Multiple Attributes

Some collection endpoints support a query parameter that performs a full-text search across multiple resource attributes.

Example Usage

query=foo
  • See endpoint documentation for details about which fields are searched for a given endpoint.

Filtering Results

You can use a variety of filter parameters to search and filter items in the response from collection endpoints.

Example Usage

name[match]=fred&sys.user.sys.id[in]=abc123,zyx987&sys.updatedAt[lt]=2018-09-01

In general the format of a filter paramter is as follows:

field[operator]=value

Operators

For each supported field, one or more operators is available. This table explains their usage:

Operator Description
eq The resource field exactly matches the specified value. E.g. name[eq]=fred (or name=fred for short)
ne The resource field does not match the specified value. E.g. name[ne]=fred
match The resource field does includes the specified value. E.g. name[match]=fre
in The resource field matches one of the specified values in a comma separated list. E.g. sys.user.sys.id[in]=abc123,zyx987
nin The resource field does not match at least one of the specified values in a comma separated list. E.g. sys.user.sys.id[nin]=abc123,zyx987
exists The resource field is not null if the specified value is true, or null if the specified value is false. E.g. sys.updatedAt[exists]=true
lt The resource field is less than the specified value. E.g. sys.updatedAt[lt]=2018-09-01
lte The resource field is less than or equal to the specified value. E.g. sys.updatedAt[lte]=2018-09-01
gt The resource field is greater than the specified value. E.g. sys.updatedAt[gt]=2018-09-01
gte The resource field is greater than or equal to the specified value. E.g. sys.updatedAt[gt]=2018-09-01

API Reference

Get all organization memberships

This endpoint returns a paginated collection of all organization memberships for this organization.

Only organization admins and owners can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/organization_memberships

Base URL

https://api.contentful.com

Supported Query Parameters

Name Details Description
skip, limit - Specify requested page of result set. See Pagination for more details.
order Supported values: role, sys.createdAt, sys.user.firstName, sys.user.lastName, sys.user.email Specify sort order of result set. See Sorting Results for more details.
include Supported values: sys.user, sys.createdBy, sys.updatedBy Specify linked resources to include in response. See Including Related Resources for more details.
query Fields searched: sys.user.id, sys.user.firstName, sys.user.lastName, sys.user.email Specify a string to search for matching resources against. See Searching Multiple Attributes for more details.
Filters See section below Specify a value to filter against for the provided attribute. See Filtering Results for more information, and below for details about supported attributes for this endpoint.

Filter Parameters

See Filtering Results for details about how to use attributes and operators to construct query filters.

Attribute Supported Operators Supported Values
role eq, ne, in, nin owner, admin, member
sys.user.sys.id eq, ne, in, nin String (id)
sys.lastActiveAt lt, lte, gt, gte, exists Datetime string (or Boolean with exists)
sys.sso.lastSignInAt lt, lte, gt, gte, exists Datetime string (or Boolean with exists)
sys.createdAt lt, lte, gt, gte Datetime string
sys.updatedAt lt, lte, gt, gte Datetime string

Path Parameters

Parameter Type Usage
organizationId string required

Headers

Parameter Type Usage
Authorization string required

Query String

Parameter Type Usage
skip integer (Page offset to skip to) optional
limit integer (Maximum number of items to return in result, per page) optional

Response

{
  "total": 1,
  "limit": 25,
  "skip": 0,
  "sys": {
    "type": "Array"
  },
  "items": [
    {
      "sys": {
        "type": "SpaceMembership",
        "id": "0xWanD4AZI2AR35wW9q51n",
        "version": 0,
        "createdAt": "2015-05-18T11:29:46.809Z",
        "createdBy": {
          "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "7BslKh9TdKGOK41VmLDjFZ"
          }
        },
        "updatedAt": "2015-05-18T11:29:46.809Z",
        "updatedBy": {
          "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "4FLrUHftHW3v2BLi9fzfjU"
          }
        },
        "user": {
          "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "7BslKh9TdKGOK41VmLDjFZ"
          }
        }
      },
      "admin": false,
      "roles": [
        {
          "sys": {
            "type": "Link",
            "linkType": "Role",
            "id": "1ElgCn1mi1UHSBLTP2v4TD"
          }
        }
      ],
      "user": {
        "sys": {
          "type": "Link",
          "linkType": "User",
          "id": "7BslKh9TdKGOK41VmLDjFZ"
        }
      }
    }
  ]
}

Get single organization membership

This endpoint returns details about an existing organization membership.

Only organization admins and owners can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required
organizationMembershipId String required

Headers

Parameter Type Usage
Authorization string required
x-contentful-enable-alpha-feature string optional

Response

{
  "sys": {
    "type": "OrganizationMembership",
    "id": "0xWanD4AZI2AR35wW9q51n",
    "version": 0,
    "createdAt": "2015-05-18T11:29:46.809Z",
    "updatedAt": "2015-05-18T11:29:46.809Z",
    "lastActiveAt": "2015-05-18T11:29:46.809Z",
    "user": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "updatedBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "createdBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "sso": {
      "isExemptFromRestrictedMode": false,
      "lastSignInAt": "2018-09-18T11:29:46.809Z",
      "exemptionReasons": []
    }
  },
  "role": "admin"
}

Create an organization membership

It is not possible to create an organization membership directly. To add a user to your organization, you need to invite them to the organization.

Note Organization Invitation API reference details will be published soon.

Update a single organization membership

This endpoint allows you to change an organization membership. Use this to update the organizational role associated with this user.

Only organization admins and owners can access this endpoint.

Endpoint: [PUT] /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required
organizationMembershipId string required

Headers

Parameter Type Usage
Authorization string required

Request Body

{
    "$ref": "#/definitions/organization-membership-update"
}

Response

{
  "sys": {
    "type": "OrganizationMembership",
    "id": "0xWanD4AZI2AR35wW9q51n",
    "version": 0,
    "createdAt": "2015-05-18T11:29:46.809Z",
    "updatedAt": "2015-05-18T11:29:46.809Z",
    "lastActiveAt": null,
    "sso": null,
    "user": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "updatedBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    },
    "createdBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "7BslKh9TdKGOK41VmLDjFZ"
      }
    }
  },
  "role": "admin"
}

Delete a single organization membership

This endpoint allows you to delete an organization membership. It only affects whether a user can access an organization, not the user account itself.

Only organization admins and owners can access this endpoint.

Note: It is not possible to delete an organization membership with an owner role if there are no other owner memberships remaining in the organization.

Endpoint: [DELETE] /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required
organizationMembershipId string required

Headers

Parameter Type Usage
Authorization string required
x-contentful-enable-alpha-feature string optional

Get all users in organization

This endpoint returns a paginated list of all users who are active members of this organization.

Only organization owners and organization admins can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/users

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required

Query String

Parameter Type Usage
skip integer (Page offset to skip to) optional
limit integer (Maximum number of items to return in result, per page) optional

Headers

Parameter Type Usage
Authorization string required

Response

{
    "total": 3,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "firstName": "Sascha",
            "lastName": "Konietzke",
            "avatarUrl": "http://a0.twimg.com/profile_images/148466442/sascha_konietzke_normal.jpg",
            "email": "user@example.com",
            "activated": true,
            "signInCount": 1277,
            "confirmed": true,
            "sys": {
                "type": "User",
                "id": "7uqvFPPLzgtVaezGvjA9U6",
                "version": 1733,
                "createdAt": "2013-04-11T20:04:37Z",
                "updatedAt": "2017-09-20T08:51:45Z"
            }
        },
        {
            "firstName": "Steeephen",
            "lastName": "Sugden",
            "avatarUrl": "https://www.gravatar.com/avatar/792867cb6657d4b936e474374985e58f?s=50&d=https%3A%2F%2Fstatic.quirely.com%2Fgatekeeper%2Fusers%2Fdefault-f33548606250cac861471edee5f997d0f50c8ad0ff68a700c394330bf0938a96.png",
            "email": "stephen@contentful.com",
            "activated": true,
            "signInCount": 4,
            "confirmed": true,
            "sys": {
                "type": "User",
                "id": "3XdAASLq5SdkZ9B97bHhKW",
                "version": 12,
                "createdAt": "2014-06-26T15:21:46Z",
                "updatedAt": "2015-12-01T14:40:35Z"
            }
        },
        {
            "firstName": "Stephen",
            "lastName": "Sugden",
            "avatarUrl": "https://www.gravatar.com/avatar/28a5abbb379d0fdddab1408d6405d6d0?s=50&d=https%3A%2F%2Fstatic.quirely.com%2Fgatekeeper%2Fusers%2Fdefault-f33548606250cac861471edee5f997d0f50c8ad0ff68a700c394330bf0938a96.png",
            "email": "stephen+no@contentful.com",
            "activated": true,
            "signInCount": 2,
            "confirmed": false,
            "sys": {
                "type": "User",
                "id": "4FuwCQbxmOx6hxCgN8fcOK",
                "version": 2,
                "createdAt": "2015-09-21T10:22:34Z",
                "updatedAt": "2015-09-28T13:18:27Z"
            }
        }
    ]
}

Get a single user in an organization

This endpoint returns details about an existing user who is a member of the organization.

Only organization owners and organization admins can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/users/{userId}

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required
userId string required

Headers

Parameter Type Usage
Authorization string required
x-contentful-enable-alpha-feature string optional

Response

{
    "firstName": "Sascha",
    "lastName": "Konietzke",
    "avatarUrl": "http://a0.twimg.com/profile_images/148466442/sascha_konietzke_normal.jpg",
    "email": "user@example.com",
    "activated": true,
    "signInCount": 1277,
    "confirmed": true,
    "sys": {
        "type": "User",
        "id": "7uqvFPPLzgtVaezGvjA9U6",
        "version": 1733,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2017-09-20T08:51:45Z"
    }
}

Get all space memberships in an organization

This endpoint returns a paginated collection of all space memberships for this organization.

Only organization admins and owners can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/space_memberships

Base URL

https://api.contentful.com

Supported Query Parameters

Name Details Description
skip, limit - Specify requested page of result set. See Pagination for more details.
order Supported values: role, sys.createdAt, sys.user.firstName, sys.user.lastName, sys.user.email Specify sort order of result set. See Sorting Results for more details.
include Supported values: sys.user, sys.createdBy, sys.updatedBy Specify linked resources to include in response. See Including Related Resources for more details.
query Fields searched: sys.user.id, sys.user.firstName, sys.user.lastName, sys.user.email Specify a string to search for matching resources against. See Searching Multiple Attributes for more details.
Filters See section below Specify a value to filter against for the provided attribute. See Filtering Results for more information, and below for details about supported attributes for this endpoint.

Filter Parameters

See Filtering Results for details about how to use attributes and operators to construct query filters.

Attribute Supported Operators Supported Values
role eq, ne, in, nin owner, admin, member
sys.user.sys.id eq, ne, in, nin String (id)
sys.lastActiveAt lt, lte, gt, gte, exists Datetime string (or Boolean with exists)
sys.sso.lastSignInAt lt, lte, gt, gte, exists Datetime string (or Boolean with exists)
sys.createdAt lt, lte, gt, gte Datetime string
sys.updatedAt lt, lte, gt, gte Datetime string

Path Parameters

Parameter Type Usage
organizationId string required

Query String

Parameter Type Usage
skip integer (Page offset to skip to) optional
limit integer (Maximum number of items to return in result, per page) optional

Headers

Parameter Type Usage
Authorization string required

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "SpaceMembership",
                "id": "0xWanD4AZI2AR35wW9q51n",
                "version": 0,
                "createdAt": "2015-05-18T11:29:46.809Z",
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "7BslKh9TdKGOK41VmLDjFZ"
                    }
                },
                "updatedAt": "2015-05-18T11:29:46.809Z",
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "4FLrUHftHW3v2BLi9fzfjU"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "7BslKh9TdKGOK41VmLDjFZ"
                    }
                }
            },
            "admin": false,
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ],
            "user": {
                "sys": {
                    "type": "Link",
                    "linkType": "User",
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
                }
            }
        }
    ]
}

Get all space memberships in an organization

This endpoint returns a paginated collection of all space memberships for this organization.

Only organization admins and owners can access this endpoint.

Endpoint: [GET] /organizations/{organizationId}/space_memberships

Base URL

https://api.contentful.com

Path Parameters

Parameter Type Usage
organizationId string required
spaceMembershipId string required

Response

{
    "sys": {
        "type": "SpaceMembership",
        "id": "0xWanD4AZI2AR35wW9q51n",
        "version": 0,
        "createdAt": "2015-05-18T11:29:46.809Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "updatedAt": "2015-05-18T11:29:46.809Z",
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "4FLrUHftHW3v2BLi9fzfjU"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        }
    },
    "admin": false,
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ],
    "user": {
        "sys": {
            "type": "Link",
            "linkType": "User",
            "id": "7BslKh9TdKGOK41VmLDjFZ"
        }
    }
}