Overview

Contentful’s User Management API helps organizations programmatically manage their organizations, organization memberships, teams, space memberships and more.

Basic API information

API Base URL https://api.contentful.com This is a read/write API

Authentication

A valid Content Management API token must be included for all requests documented in this section, as follows:

• In the Authorization header, specifically as: Authorization: Bearer MY_ACCESS_TOKEN.
• In the access_token URL query parameter: ?access_token=MY_ACCESS_TOKEN

For security reasons Contentful strongly recommends passing the token via the Authorization header.

Note that all permissions and access rights for API endpoints in this section are derived from the user on whose behalf the access token was generated.

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=50

Example response:

1
{
2
    "sys": {
3
        "type": "Array"
4
    },
5
    "skip": 50,
6
    "limit": 25,
7
    "total": 1256,
8
    "items": [ /* 25 individual resources */ ]
9
}

Request Parameters

Response Attributes

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

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.

Including Related Resources

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=sys.user,sys.createdBy

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

Request

GET /organizations/some_organization_id/organization_memberships

Response

1
{
2
    "total": 1,
3
    "limit": 25,
4
    "skip": 0,
5
    "sys": {
6
        "type": "Array"
7
    },
8
    "items": [{
9
        "sys": {
10
            "type": "OrganizationMembership",
11
            "id": "0xWanD4AZI2AR35wW9q51n",
12
            "version": 0,
13
            "createdAt": "2015-05-18T11:29:46.809Z",
14
            "updatedAt": "2015-05-18T11:29:46.809Z",
15
            "lastActiveAt": null,
16
            "status": "active",
17
            "sso": null,
18
            "user": {
19
                "sys": {
20
                    "type": "Link",
21
                    "linkType": "User",
22
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
23
                }
24
            },
25
            "updatedBy": {
26
                "sys": {
27
                    "type": "Link",
28
                    "linkType": "User",
29
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
30
                }
31
            },
32
            "createdBy": {
33
                "sys": {
34
                    "type": "Link",
35
                    "linkType": "User",
36
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
37
                }
38
            }
39
        },
40
        "role": "admin"
41
    }]
42
}

To fetch the linked users referenced in sys.user and sys.createdBy, you would normally need to make subsequent API calls.

Using the include parameter you can request the linked users to be “included” in the response:

Request

GET /organizations/some_organization_id/organization_memberships?include=sys.user,sys.updatedBy

Response

1
{
2
    // ...
3
    "items": [{
4
        "sys": {
5
            "type": "OrganizationMembership",
6
            "id": "0xWanD4AZI2AR35wW9q51n",
7
            "version": 0,
8
            "createdAt": "2015-05-18T11:29:46.809Z",
9
            "updatedAt": "2015-05-18T11:29:46.809Z",
10
            "lastActiveAt": null,
11
            "status": "active",
12
            "sso": null,
13
            "user": {
14
                "sys": {
15
                    "type": "Link",
16
                    "linkType": "User",
17
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
18
                }
19
            },
20
            "updatedBy": {
21
                "sys": {
22
                    "type": "Link",
23
                    "linkType": "User",
24
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
25
                }
26
            },
27
            "createdBy": {
28
                "sys": {
29
                    "type": "Link",
30
                    "linkType": "User",
31
                    "id": "7BslKh9TdKGOK41VmLDjFZ"
32
                }
33
            }
34
        },
35
        "role": "admin"
36
    }],
37
    "includes": {
38
        "User": [{
39
                "firstName": "Jane",
40
                "lastName": "Smith",
41
                "sys": {
42
                    "id": "7BslKh9TdKGOK41VmLDjFZ",
43
                    "type": "User"
44
                }
45
            },
46
            {
47
                "firstName": "Mary",
48
                "lastName": "Jones",
49
                "sys": {
50
                    "id": "7BslKh9TdKGOK41VmLDjFZ",
51
                    "type": "User"
52
                }
53
            }
54
        ]
55
    }
56
}

As you can see, the link objects (user and createdBy) are now fully resolved inside the includes attribute in the response, organized by type (i.e. User).

Additional Notes

• Linked resources are returned in the includes attribute of the response body, organized by type.
• 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 for a given collection endpoint.

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 parameter is as follows:

field[operator]=value

Operators

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