Documentation / API reference / User Management API

User Management API

Introduction

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

Disclaimer: The User Management API is available for Premium/Enterprise customers on current pricing plans.

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:

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

Request Parameters

Parameter	Description
`skip`	Specify an offset (as an integer) to paginate through results. The first "page" is `skip=0`. If your limit is `10`, the second page would be `skip=10`, the third would be `skip=20`, and so on.
`limit`	Specify (as an integer) the maximum number of results. The maximum allowed value for limit is 100.

Response Attributes

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

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

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [{
        "sys": {
            "type": "OrganizationMembership",
            "id": "0xWanD4AZI2AR35wW9q51n",
            "version": 0,
            "createdAt": "2015-05-18T11:29:46.809Z",
            "updatedAt": "2015-05-18T11:29:46.809Z",
            "lastActiveAt": null,
            "status": "active",
            "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"
    }]
}

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

{
    // ...
    "items": [{
        "sys": {
            "type": "OrganizationMembership",
            "id": "0xWanD4AZI2AR35wW9q51n",
            "version": 0,
            "createdAt": "2015-05-18T11:29:46.809Z",
            "updatedAt": "2015-05-18T11:29:46.809Z",
            "lastActiveAt": null,
            "status": "active",
            "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"
    }],
    "includes": {
        "User": [{
                "firstName": "Jane",
                "lastName": "Smith",
                "sys": {
                    "id": "7BslKh9TdKGOK41VmLDjFZ",
                    "type": "User"
                }
            },
            {
                "firstName": "Mary",
                "lastName": "Jones",
                "sys": {
                    "id": "7BslKh9TdKGOK41VmLDjFZ",
                    "type": "User"
                }
            }
        ]
    }
}

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:

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[gte]=2018-09-01`

Reference

Organization Memberships

Organization memberships represent the relationship between a single Contentful user and your organization. In other words, this data object defines explicitly who is a member of your organization.

Get all organization memberships

GET /organizations/{organizationId}/organization_memberships

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

All organization members can access this endpoint and will receive a scoped response.

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.lastActiveAt`, `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`, `developer`, `member`
`sys.status`	`eq`, `ne`, `in`, `nin`	`pending`, `active`
`sys.user.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)
`sys.user.firstName`	`eq`, `ne`, `exists`	String
`sys.user.lastName`	`eq`, `ne`, `exists`	String
`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

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [{
        "sys": {
            "type": "OrganizationMembership",
            "id": "0xWanD4AZI2AR35wW9q51n",
            "version": 0,
            "createdAt": "2015-05-18T11:29:46.809Z",
            "updatedAt": "2015-05-18T11:29:46.809Z",
            "lastActiveAt": null,
            "status": "active",
            "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"
        "isExemptFromRestrictedMode":true,
    }]
}

Get a single organization membership

GET /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

This endpoint returns details about an existing organization membership.

All organization members can access this endpoint.

Response

{
    "sys": {
        "type": "OrganizationMembership",
        "id": "0xWanD4AZI2AR35wW9q51n",
        "version": 0,
        "status": "active",
        "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.

Inviting a user to your organization has the indirect side effect of creating an organization membership, with a status of pending.

See the Invitations section below for complete details.

Update a single organization membership

PUT /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

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

Only organization admins and owners can access this endpoint.

Request Body

Parameter	Type	Usage
`role`	string	required; one of `member`, `developer`, `admin`, `owner`

Response

{
    "sys": {
        "type": "OrganizationMembership",
        "id": "0xWanD4AZI2AR35wW9q51n",
        "version": 0,
        "createdAt": "2015-05-18T11:29:46.809Z",
        "updatedAt": "2015-05-18T11:29:46.809Z",
        "lastActiveAt": null,
        "status": "active",
        "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

DELETE /organizations/{organizationId}/organization_memberships/{organizationMembershipId}

This endpoint deletes an organization membership. This action only affects whether a user can access an organization; it does not remove the user account itself.

Only organization admins and owners can access this endpoint. The user associated with the space membership also has access to this endpoint (so that they have permission to remove themselves from an organization).

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.

Response

Status: 204 No Content

Invitations

Invitations are the entities used to add new users to your organization. Users will receive an invitation (presently via email), which they must explicitly accept before they can access your organization.

Note that a side effect of creating an invitation is that an organization membership object is created in the "pending" state. Once you have invited a user, you may add them to teams and spaces immediately, without waiting for them to accept.

Note: These endpoints are in "alpha" state, which means that breaking changes might be introduced in the future

Create an invitation (alpha)

POST /organizations/{organizationId}/invitations

Use this endpoint to invite someone to your organization.

Only organization admins and owners can access this endpoint.

Request Body

Parameter	Type	Usage
`email`	string	required
`firstName`	string	optional
`lastName`	string	optional
`role`	string	optional; one of `member`, `developer`, `admin`, `owner`

Response

{
    "sys": {
        "id": "aasfdsgfesagrwg32ggs",
        "type": "Invitation",
        "status": "open",
        "organizationMembership": {
            "sys": {
                "type": "Link",
                "linkType": "OrganizationMembership",
                "id": "65jhgf45jrt8j945j89gt"
            }
        },
        "createdAt": "2019-01-15T08:03:16.007Z",
        "updatedAt": "2019-01-15T08:03:16.007Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "dsf4tgfd43gf4t3g4"
            }
        },
        "user": null,
        "invitationUrl": "https://be.contentful.com/invitations/aasfdsgfesagrwg32ggs?token=xyzpdq"
    }
}

Get a single invitation (alpha)

GET /organizations/{organizationId}/invitations/{invitationId}

This endpoint returns details about an existing invitation. The user attribute will be null until the invitation has been accepted by a user.

Only organization admins and owners can access this endpoint.

Response

{
    "sys": {
        "id": "aasfdsgfesagrwg32ggs",
        "type": "Invitation",
        "status": "open",
        "organizationMembership": {
            "sys": {
                "type": "Link",
                "linkType": "OrganizationMembership",
                "id": "65jhgf45jrt8j945j89gt"
            }
        },
        "createdAt": "2019-01-15T08:03:16.007Z",
        "updatedAt": "2019-01-15T08:03:16.007Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "dsf4tgfd43gf4t3g4"
            }
        },
        "user": null,
        "invitationUrl": ""
    }
}

Delete an invitation

At present, it is not possible to delete an invitation directly via API.

To remove an invitation, you can delete the organization membership associated with it. This action will delete all invitations associated with the organization membership.

Teams

A team is a group of users in your organization. Teams can be given access to a space (via team space memberships) in the same way an individual user can.

Get all teams for an organization

GET /organizations/{organizationId}/teams

This endpoint returns a paginated collection of all teams in this organization.

All organization members can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [{
        "name": "Home Department",
        "description": "Furniture and accessories",
        "sys": {
            "id": "2v0NGpymMx5dc1sWjtiarg",
            "type": "Team",
            "organization": {
                "sys": {
                    "type": "Link",
                    "linkType": "Organization",
                    "id": "4EJGvuLTBUMG2A6wS8gfAS"
                }
            },
            "createdAt": "2373-05-20T00:50:57.521Z",
            "updatedAt": "3882-12-12T21:02:17.948Z",
            "createdBy": {
                "sys": {
                    "type": "Link",
                    "linkType": "User",
                    "id": "6i4t6xastbPBhgW7xDtpPH"
                }
            },
            "updatedBy": {
                "sys": {
                    "type": "Link",
                    "linkType": "User",
                    "id": "4RP9VsYx86a44lASXtinmi"
                }
            },
            "memberCount": 0
        }
    }]
}

Get all teams for a space

GET /spaces/{spaceId}/teams

This endpoint returns a paginated collection of all teams in this space.

All space members can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [{
        "name": "Home Department",
        "description": "Furniture and accessories",
        "sys": {
            "id": "2v0NGpymMx5dc1sWjtiarg",
            "type": "Team",
            "organization": {
                "sys": {
                    "type": "Link",
                    "linkType": "Organization",
                    "id": "4EJGvuLTBUMG2A6wS8gfAS"
                }
            },
            "createdAt": "2373-05-20T00:50:57.521Z",
            "updatedAt": "3882-12-12T21:02:17.948Z",
            "createdBy": {
                "sys": {
                    "type": "Link",
                    "linkType": "User",
                    "id": "6i4t6xastbPBhgW7xDtpPH"
                }
            },
            "updatedBy": {
                "sys": {
                    "type": "Link",
                    "linkType": "User",
                    "id": "4RP9VsYx86a44lASXtinmi"
                }
            },
            "memberCount": 0
        }
    }]
}

Get a single team

GET /organizations/{organizationId}/teams/{teamId}

This endpoint returns details about an existing team.

All organization members can access this endpoint.

Response

{
    "name": "Home Department",
    "description": "Furniture and accessories",
    "sys": {
        "id": "2v0NGpymMx5dc1sWjtiarg",
        "type": "Team",
        "organization": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "4EJGvuLTBUMG2A6wS8gfAS"
            }
        },
        "createdAt": "2373-05-20T00:50:57.521Z",
        "updatedAt": "3882-12-12T21:02:17.948Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "6i4t6xastbPBhgW7xDtpPH"
            }
        },
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "4RP9VsYx86a44lASXtinmi"
            }
        },
        "memberCount": 0
    }
}

Create a team

POST /organizations/{organizationId}/teams

This endpoint creates a new team in this organization.

Only organization admins and owners can access this endpoint.

Request Body

Parameter	Type	Usage
`name`	string	required
`description`	string or null	required

Response

{
    "name": "Project Editors",
    "description": "",
    "sys": {
        "id": "7BslKh9TdKGOK41VmLDjFZ",
        "type": "Team",
        "organization": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "4EJGvuLTBUMG2A6wS8gfAS"
            }
        },
        "createdAt": "4723-11-14T02:01:24.016Z",
        "updatedAt": "5087-06-17T18:24:44.837Z",
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "memberCount": 0
    }
}

Update a single team

PUT /organizations/{organizationId}/teams/{teamId}

This endpoint updates the data associated with a team.

Only organization admins and owners can access this endpoint.

Request Body

Parameter	Type	Usage
`name`	string	required
`description`	string or null	required

Response

{
    "name": "Project Editors",
    "description": "",
    "sys": {
        "id": "7BslKh9TdKGOK41VmLDjFZ",
        "type": "Team",
        "organization": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "4EJGvuLTBUMG2A6wS8gfAS"
            }
        },
        "createdAt": "4723-11-14T02:01:24.016Z",
        "updatedAt": "5087-06-17T18:24:44.837Z",
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "memberCount": 0
    }
}

Delete a single team

DELETE /organizations/{organizationId}/teams/{teamId}

This endpoint deletes a team.

Only organization admins and owners can access this endpoint.

Response

Status: 204 No Content

Team Memberships

Team memberships represent the relationship between an organization member and a team within your organization. In other words, they are the data object that defines explicitly who is a member of a team.

Get all team memberships in a team

GET /organizations/{organizationId}/teams/{teamId}/team_memberships

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

All organization members can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`order`	Supported values: `sys.createdAt`, `sys.updatedAt`	Specify sort order of result set. See Sorting Results for more details.
`include`	Supported values: `sys.createdBy`, `sys.updatedBy`, `sys.organizationMembership`, `sys.user`	Specify linked resources to include in response. See Including Related Resources for more details.

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "TeamMembership",
                "id": "5xKNPxTNPnKr8JHNHYbQeC",
                "organization": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Organization",
                        "id": "4EJGvuLTBUMG2A6wS8gfAS"
                    }
                },
                "team": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Organization",
                        "id": "4E6i5or8iabA6wS8gfASfa"
                    }
                },
                "createdAt": "4511-01-18T05:03:01.695Z",
                "updatedAt": "4203-08-22T19:00:01.887Z",
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3Z6OpTgoCqMTwQ331UvyF4"
                    }
                },
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "6i5or8iabD6qwHCK7JgGLn"
                    }
                },
                "organizationMembership": {
                    "sys": {
                        "type": "Link",
                        "linkType": "OrganizationMembership",
                        "id": "1UeTxCQ2SDqNgnE5zBvruF"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "1VVPdngQPz6Qo5Qbba4zzY"
                    }
                }
            }
        }
    ]
}

Get all team memberships in an organization

GET /organizations/{organizationId}/team_memberships

This endpoint returns a paginated collection of all team memberships across all teams in the organization.

All organization members can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`order`	Supported values: `sys.createdAt`, `sys.updatedAt`	Specify sort order of result set. See Sorting Results for more details.
`include`	Supported values: `sys.team`	Specify linked resources to include in response. See Including Related Resources 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
`sys.organizationMembership.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "TeamMembership",
                "id": "5xKNPxTNPnKr8JHNHYbQeC",
                "organization": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Organization",
                        "id": "4EJGvuLTBUMG2A6wS8gfAS"
                    }
                },
                "team": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Organization",
                        "id": "4E6i5or8iabA6wS8gfASfa"
                    }
                },
                "createdAt": "4511-01-18T05:03:01.695Z",
                "updatedAt": "4203-08-22T19:00:01.887Z",
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3Z6OpTgoCqMTwQ331UvyF4"
                    }
                },
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "6i5or8iabD6qwHCK7JgGLn"
                    }
                },
                "organizationMembership": {
                    "sys": {
                        "type": "Link",
                        "linkType": "OrganizationMembership",
                        "id": "1UeTxCQ2SDqNgnE5zBvruF"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "1VVPdngQPz6Qo5Qbba4zzY"
                    }
                }
            }
        }
    ]
}

Get a single team membership

GET /organizations/{organizationId}/teams/{teamId}/team_memberships/{teamMembershipId}

This endpoint returns details about an existing team membership.

All organization members can access this endpoint.

Response

{
    "sys": {
        "type": "TeamMembership",
        "id": "5xKNPxTNPnKr8JHNHYbQeC",
        "organization": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "4EJGvuLTBUMG2A6wS8gfAS"
            }
        },
        "team": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "OpTgoCqMTwTBUMG2A6w7Jg"
            }
        },
        "createdAt": "4511-01-18T05:03:01.695Z",
        "updatedAt": "4203-08-22T19:00:01.887Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "3Z6OpTgoCqMTwQ331UvyF4"
            }
        },
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "6i5or8iabD6qwHCK7JgGLn"
            }
        },
        "organizationMembership": {
            "sys": {
                "type": "Link",
                "linkType": "OrganizationMembership",
                "id": "1UeTxCQ2SDqNgnE5zBvruF"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "1VVPdngQPz6Qo5Qbba4zzY"
            }
        }
    }
}

Create a team membership

POST /organizations/{organizationId}/teams/{teamId}/team_memberships

This endpoint creates a new team membership in this team.

Only organization admins and owners can access this endpoint.

Request Body

Parameter	Type	Usage
`organizationMembershipId`	string	required

Response

{
    "sys": {
        "type": "TeamMembership",
        "id": "5sjDwHAf1FRG65kPCwgzxc",
        "organization": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "4EJGvuLTBUMG2A6wS8gfAS"
            }
        },
        "team": {
            "sys": {
                "type": "Link",
                "linkType": "Organization",
                "id": "OpTgoCqMTwTBUMG2A6w7Jg"
            }
        },
        "createdAt": "4471-03-29T09:18:21.619Z",
        "updatedAt": "4034-04-24T14:33:27.720Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "5sjDwHAf1FRG65kPCwgzxc"
            }
        },
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "5sjDwHAf1FRG65kPCwgzxc"
            }
        },
        "organizationMembership": {
            "sys": {
                "type": "Link",
                "linkType": "OrganizationMembership",
                "id": "2J75WDB0QSfoBCn2IYTXzm"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "3sTeMpHKBy4Yycw6xmki6W"
            }
        }
    }
}

Delete a single team membership

DELETE /organizations/{organizationId}/teams/{teamId}/team_memberships/{teamMembershipId}

This endpoint deletes a team membership.

Only organization admins and owners can access this endpoint.

Response

Status: 204 No Content

Space Memberships

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.

Get all space memberships in a space

GET /spaces/{spaceId}/space_memberships

This endpoint returns a paginated list of all the space memberships in a space.

All space members can access this endopint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`include`	Supported values: `sys.user`	Specify linked resources to include in response. See Including Related Resources for more details.

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "admin": false,
            "sys": {
                "type": "SpaceMembership",
                "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
                "version": 0,
                "createdAt": "2013-04-11T20:04:37Z",
                "updatedAt": "2014-05-11T20:04:37Z",
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3Z6OpTgoCqMTwQ331UvyF4"
                    }
                },
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "6i5or8iabD6qwHCK7JgGLn"
                    }
                },
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "7uqvFPPLzgtVaezGvjA9U6"
                    }
                },
            },
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ]
        }
    ]
}

Get all space memberships in an organization

GET /organizations/{organizationId}/space_memberships

This endpoint returns a paginated list of all space memberships across all spaces in the organization.

Only organization admins and owners can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`order`	Supported values: `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: `roles`, `sys.user`, `sys.createdBy`, `sys.updatedBy`, `sys.space`	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
`admin`	`eq`, `ne`	Boolean
`roles.sys.id`	`eq`, `in`	String (id)
`roles.name`	`eq`, `ne`, `nin`, `match`	String
`sys.user.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)
`sys.space.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)
`sys.space.name`	`eq`, `ne`, `in`, `nin`	String
`sys.organizationMembership.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)
`sys.createdAt`	`lt`, `lte`, `gt`, `gte`	Datetime string
`sys.updatedAt`	`lt`, `lte`, `gt`, `gte`	Datetime string

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "admin": false,
            "sys": {
                "type": "SpaceMembership",
                "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
                "version": 0,
                "createdAt": "2013-04-11T20:04:37Z",
                "updatedAt": "2014-05-11T20:04:37Z",
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3Z6OpTgoCqMTwQ331UvyF4"
                    }
                },
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "6i5or8iabD6qwHCK7JgGLn"
                    }
                },
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "7uqvFPPLzgtVaezGvjA9U6"
                    }
                }
            },
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ]
        }
    ]
}

Get a single space membership

GET /spaces/{spaceId}/space_memberships/{spaceMembershipId}

GET /organizations/{organizationId}/space_memberships/{spaceMembershipId}

These endpoints return details about an existing space membership.

The first endpoint (scoped to a space) is accessible to all space members; the second (scoped to an organization) is accessible only to organization admin and owners.

Response

{
    "admin": false,
    "sys": {
        "type": "SpaceMembership",
        "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
        "version": 0,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2014-05-11T20:04:37Z",
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        },
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "34BcPDYW0r6kwCJV2lYevQ"
            }
        },
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "34BcPDYW0r6kwCJV2lYevQ"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7uqvFPPLzgtVaezGvjA9U6"
            }
        }
    },
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Create a space membership

POST /spaces/{spaceId}/space_memberships

Use this endpoint to create a space membership. A user can either be designated as an admin or assigned to one or more roles. The user must already exist in the organization.

Only organization admins, owners, and space admins can access this endpoint.

Note: For legacy reasons, the user you are creating a space membership for needs to be identified by their email address. This email address must match the email address of the user associated with an existing organization membership in your organization.

Request Body

Parameter	Type	Usage
`admin`	boolean	required
`roles`	array(Role)	required; must contain at least one role if admin is `false` (see also Roles)
`email`	string	required

Response

{
    "admin": false,
    "sys": {
        "type": "SpaceMembership",
        "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
        "version": 0,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2013-04-11T20:04:37Z",
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        },
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "34BcPDYW0r6kwCJV2lYevQ"
            }
        },
        "updatedBy": null,
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7uqvFPPLzgtVaezGvjA9U6"
            }
        }
    },
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Update a space membership

PUT /spaces/{spaceId}/space_memberships/{spaceMembershipId}

This endpoint updates a space membership. Use this to change the roles for a user or make them an admin within the space.

Only organization admins, owners, and space admins can access this endpoint.

Request Body

Parameter	Type	Usage
`admin`	boolean	required
`roles`	array(Role)	required; must contain at least one role if admin is `false` (see also Roles)
`email`	string	required

Response

{
    "admin": false,
    "sys": {
        "type": "SpaceMembership",
        "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
        "version": 0,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2014-05-11T20:04:37Z",
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        },
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "34BcPDYW0r6kwCJV2lYevQ"
            }
        },
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "34BcPDYW0r6kwCJV2lYevQ"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7uqvFPPLzgtVaezGvjA9U6"
            }
        }
    },
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Delete a space membership

DELETE /spaces/{spaceId}/space_memberships/{spaceMembershipId}

This endpoint deletes a space membership.

Only organization admins, owners, and space admins can access this endpoint. The user associated with the space membership also has access to this endpoint (so that they have permission to remove themselves from an organization).

Response

Status: 204 No Content

Team Space Memberships

Team space memberships are just like space memberships, except that while space memberships grant space access to a single user, team space memberships grant access to an entire team.

Get all team space memberships in a space

GET /spaces/{spaceId}/team_space_memberships

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

Only organization admins, owners, and space admins can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`order`	Supported values: `sys.updatedAt`, `sys.createdAt`	Specify sort order of result set. See Sorting Results for more details.
`include`	Supported values: `roles`, `sys.team`	Specify linked resources to include in response. See Including Related Resources 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
`sys.id`	`eq`, `in`	String (id)

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "TeamSpaceMembership",
                "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"
                    }
                },
                "team": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Team",
                        "id": "7BslKh9TdKGOK41VmLDjFZ"
                    }
                },
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                }
            },
            "admin": false,
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ]
        }
    ]
}

Get all team space memberships in an organization

This endpoint returns a paginated collection of all team space memberships across all spaces in the organization.

All organization members can access this endpoint.

GET /organizations/{organizationId}/team_space_memberships

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`order`	Supported values: `sys.updatedAt`, `sys.createdAt`	Specify sort order of result set. See Sorting Results for more details.
`include`	Supported values: `roles`, `sys.createdBy`, `sys.updatedBy`, `sys.space`, `sys.team`	Specify linked resources to include in response. See Including Related Resources 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
`roles.name`	`eq`, `ne`, `in`, `nin`	String
`roles.sys.id`	`eq`, `in`	String (id)
`sys.createdAt`	`lt`, `lte`, `gt`, `gte`	Datetime string
`sys.updatedAt`	`lt`, `lte`, `gt`, `gte`	Datetime string
`sys.team.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)
`sys.space.name`	`eq`, `ne`, `in`, `nin`, `match`	String
`sys.space.sys.id`	`eq`, `ne`, `in`, `nin`	String (id)

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "TeamSpaceMembership",
                "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"
                    }
                },
                "team": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Team",
                        "id": "7BslKh9TdKGOK41VmLDjFZ"
                    }
                },
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                }
            },
            "admin": false,
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ]
        }
    ]
}

Get a single team space membership

GET /spaces/{spaceId}/team_space_memberships/{teamSpaceMembershipId}

GET /organizations/{organizationId}/team_space_memberships/{teamSpaceMembershipId}

These endpoints return details about an existing team space membership.

The first endpoint (scoped to a space) is accessible to all space members; the second (scoped to an organization) is accessible to all organization members.

Response

{
    "sys": {
        "type": "TeamSpaceMembership",
        "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"
            }
        },
        "team": {
            "sys": {
                "type": "Link",
                "linkType": "Team",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        }
    },
    "admin": false,
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Create a team space membership

POST /spaces/{spaceId}/team_space_memberships

Use this endpoint to create a team space membership. A team can either be designated as an admin or assigned to one or more roles. All active members of the team will inherit these permissions.

Only organization admins, owners, and space admins can access this endpoint.

Request Headers

Parameter	Type	Usage
`X-Contentful-Team`	string	required; the `id` of the team for this membership

Request Body

Parameter	Type	Usage
`admin`	boolean	required
`roles`	array(Role)	required; must contain at least one role if admin is `false` (see also Roles)

Response

{
    "sys": {
        "type": "TeamSpaceMembership",
        "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"
            }
        },
        "team": {
            "sys": {
                "type": "Link",
                "linkType": "Team",
                "id": "7BslKh9TdKGOK41VmLDjFZ"
            }
        },
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        }
    },
    "admin": false,
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Update a team space membership

PUT /spaces/{spaceId}/team_space_memberships/{teamSpaceMembershipId}

This endpoint updates a team space membership. Use this to change the roles for a team or make the team an admin within the space.

Only organization admins, owners, and space admins can access this endpoint.

Request Body

Parameter	Type	Usage
`admin`	boolean	required
`roles`	array(Role)	required; must contain at least one role if admin is `false` (see also Roles)

Response

{
    "sys": {
        "type": "TeamSpaceMembership",
        "id": "362gCn1mi1UHSBLTP2v4TD",
        "version": 0,
        "createdAt": "3899-05-25T21:00:34.690Z",
        "createdBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        },
        "updatedAt": "3089-09-11T13:51:59.504Z",
        "updatedBy": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        },
        "team": {
            "sys": {
                "type": "Link",
                "linkType": "Team",
                "id": "gCn1mi1El1UHSBLTP2v4TD"
            }
        },
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "5ae45h2qifno"
            }
        }
    },
    "admin": false,
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        },
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "54gtw51mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Delete a team space membership

DELETE /spaces/{spaceId}/team_space_memberships/{teamSpaceMembershipId}

This endpoint deletes a team space membership.

Only organization admins, owners, and space admins can access this endpoint.

Response

Status: 204 No Content

Space Members

An individual user in your organization can be given access to a space directly, via a space membership, or indirectly, via their membership in a team that has itself been granted access via a team space membership. The access rights of a user in a space are calculated by combining the rights of all such memberships through which the user has derived access.

Because this complex relationship between a user and a space can be difficult to reason about, the space member entity was developed. This entity reveals exactly which individual users have access to a space, and reveals their combined access rights within a single object. Furthermore, it provides a link to the related membership objects from which their access is derived.

Get all space members in a space

GET /spaces/{spaceId}/space_members

This endpoint returns a paginated collection of all the space members in a space. This collection represents the set of all users in your organization who have access to the space.

All space members can access this endpoint.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`include`	Supported values: `sys.user`	Specify linked resources to include in response. See Including Related Resources for more details.

Response

{
    "total": 1,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "sys": {
                "type": "SpaceMember",
                "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
                "version": 1,
                "createdAt": "2013-04-11T20:04:37Z",
                "updatedAt": "2014-05-11T20:04:37Z",
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                },
                "user": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "7uqvFPPLzgtVaezGvjA9U6"
                    }
                },
                "relatedMemberships": [
                    {
                        "sys": {
                            "type": "Link",
                            "linkType": "SpaceMembership",
                            "id": "2G3gCn1mi1UHSBLTP2v4TI"
                        }
                    },
                    {
                        "sys": {
                            "type": "Link",
                            "linkType": "TeamSpaceMembership",
                            "id": "4FG3gCn1mi1UHSBLTP2v3GB"
                        }
                    }
                ]
            },
            "admin": false,
            "roles": [
                {
                    "sys": {
                        "type": "Link",
                        "linkType": "Role",
                        "id": "1ElgCn1mi1UHSBLTP2v4TD"
                    }
                }
            ]
        }
    ]
}

Get a single space member

GET /spaces/{spaceId}/space_members/{spaceMemberId}

This endpoint returns the details of a space member.

Response

{
    "sys": {
        "type": "SpaceMember",
        "id": "jn066pnp3hgr-7uqvFPPLzgtVaezGvjA9U6",
        "version": 1,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2014-05-11T20:04:37Z",
        "space": {
            "sys": {
                "type": "Link",
                "linkType": "Space",
                "id": "jn066pnp3hgr"
            }
        },
        "user": {
            "sys": {
                "type": "Link",
                "linkType": "User",
                "id": "7uqvFPPLzgtVaezGvjA9U6"
            }
        },
        "relatedMemberships": [
            {
                "sys": {
                    "type": "Link",
                    "linkType": "SpaceMembership",
                    "id": "2G3gCn1mi1UHSBLTP2v4TI"
                }
            },
            {
                "sys": {
                    "type": "Link",
                    "linkType": "TeamSpaceMembership",
                    "id": "4FG3gCn1mi1UHSBLTP2v3GB"
                }
            }
        ]
    },
    "admin": false,
    "roles": [
        {
            "sys": {
                "type": "Link",
                "linkType": "Role",
                "id": "1ElgCn1mi1UHSBLTP2v4TD"
            }
        }
    ]
}

Space Roles

A role inside a space represents a collection of policies which determine what kind of access a user (or team) has within that space. See the complete documentation for space roles in the Content Management API for more details about how roles and policies can be managed via API.

Note: Space roles should not be confused with the organization role, which is an attribute of an organization membership.

Get all space roles in an organization

GET /organizations/{organizationId}/roles

This endpoint returns a paginated list of all roles from all spaces across the organization.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`include`	Supported values: `sys.space`	Specify linked resources to include in response. See Including Related Resources for more details.

Response

{
    "total": 2,
    "limit": 25,
    "skip": 0,
    "sys": {
        "type": "Array"
    },
    "items": [
        {
            "name": "Developer",
            "description": "Allows reading Entries and managing API Keys",
            "policies": [
                {
                    "effect": "allow",
                    "actions": [
                        "read"
                    ],
                    "constraint": {
                        "and": [
                            {
                                "equals": [
                                    {
                                        "doc": "sys.type"
                                    },
                                    "Entry"
                                ]
                            }
                        ]
                    }
                },
                {
                    "effect": "allow",
                    "actions": [
                        "read"
                    ],
                    "constraint": {
                        "and": [
                            {
                                "equals": [
                                    {
                                        "doc": "sys.type"
                                    },
                                    "Asset"
                                ]
                            }
                        ]
                    }
                }
            ],
            "permissions": {
                "ContentModel": [
                    "read"
                ],
                "Settings": [],
                "ContentDelivery": "all"
            },
            "sys": {
                "type": "Role",
                "id": "4hD58EyqKCOyHwo2nTzojk",
                "version": 0,
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                },
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3JE87mfI5hDuAaq0hpbbEh"
                    }
                },
                "createdAt": "2017-11-09T09:16:10Z",
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3JE87mfI5hDuAaq0hpbbEh"
                    }
                },
                "updatedAt": "2017-11-09T09:16:10Z"
            }
        },
        {
            "name": "Editor",
            "description": "Allows editing, publishing and archiving of content",
            "policies": [
                {
                    "effect": "allow",
                    "actions": "all",
                    "constraint": {
                        "and": [
                            {
                                "equals": [
                                    {
                                        "doc": "sys.type"
                                    },
                                    "Entry"
                                ]
                            }
                        ]
                    }
                },
                {
                    "effect": "allow",
                    "actions": "all",
                    "constraint": {
                        "and": [
                            {
                                "equals": [
                                    {
                                        "doc": "sys.type"
                                    },
                                    "Asset"
                                ]
                            }
                        ]
                    }
                }
            ],
            "permissions": {
                "ContentModel": [
                    "read"
                ],
                "Settings": [],
                "ContentDelivery": []
            },
            "sys": {
                "type": "Role",
                "id": "4hDOJRz3lT01Jv6WVogTfE",
                "version": 0,
                "space": {
                    "sys": {
                        "type": "Link",
                        "linkType": "Space",
                        "id": "jn066pnp3hgr"
                    }
                },
                "createdBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3JE87mfI5hDuAaq0hpbbEh"
                    }
                },
                "createdAt": "2017-11-09T09:16:10Z",
                "updatedBy": {
                    "sys": {
                        "type": "Link",
                        "linkType": "User",
                        "id": "3JE87mfI5hDuAaq0hpbbEh"
                    }
                },
                "updatedAt": "2017-11-09T09:16:10Z"
            }
        }
    ]
}

Users

The user entity provides identifying information about members of your organization, teams, and spaces.

Note: The user object is owned by the individual whose account is associated with it. Only this individual can make changes to the user object, including deleting it. Organizations indirectly maintain control over users within the organization via the several membership objects described in this documentation.

Get all users in organization

GET /organizations/{organizationId}/users

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

This endpoint is accessible by all members of the organization.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.
`query`	Fields searched: `sys.id`, `firstName`, `lastName`, `email`	Specify a string to search for matching resources against. See Searching Multiple Attributes for more details.

Response

{
    "total": 2,
    "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,
            "2faEnabled": 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,
            "2faEnabled": true,
            "sys": {
                "type": "User",
                "id": "3XdAASLq5SdkZ9B97bHhKW",
                "version": 12,
                "createdAt": "2014-06-26T15:21:46Z",
                "updatedAt": "2015-12-01T14:40:35Z"
            }
        }
    ]
}

Get all users in a space

GET /spaces/{spaceId}/users

This endpoint returns a paginated list of all users in a space. Note that this includes both users who have access directly, via a space membership, as well as indirectly, via membership in a team that has access to the space via a team space membership.

This endpoint is accessible by all members of the space.

Query Parameters

Name	Details	Description
`skip`, `limit`	-	Specify requested page of result set. See Pagination for more details.

Response

{
    "total": 2,
    "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,
            "2faEnabled": 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,
            "2faEnabled": true,
            "sys": {
                "type": "User",
                "id": "3XdAASLq5SdkZ9B97bHhKW",
                "version": 12,
                "createdAt": "2014-06-26T15:21:46Z",
                "updatedAt": "2015-12-01T14:40:35Z"
            }
        }
    ]
}

Get a single user

GET /organizations/{organizationId}/users/{userId}

GET /spaces/{spaceId}/users/{userId}

These endpoints return details about an existing user, either in the context of an organization or a space.

The first endpoint (scoped to an organization) is accessible to all organization members; the second (scoped to a space) is accessible to all members of that space.

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,
    "2faEnabled": true,
    "sys": {
        "type": "User",
        "id": "7uqvFPPLzgtVaezGvjA9U6",
        "version": 1733,
        "createdAt": "2013-04-11T20:04:37Z",
        "updatedAt": "2017-09-20T08:51:45Z"
    }
}

Get all environment templates

GET /organizations/{organization_id}/environment_templates

This action returns a collection with all the environment templates in the organization repository. The templates are ordered by creation date descending.

Response

{
  "sys": {
    "type": "Array"
  },
  "pages": {},
  "limit": 100,
  "items": [
    {
  "sys": {
    "id": "2nZrYQn7N7xijNAOhkKUrH",
    "type": "EnvironmentTemplate",
    "createdAt": "2022-02-01T06:43:57.044Z",
    "updatedAt": "2022-02-01T06:43:57.044Z",
    "version": 1,
    "createdBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "75cxRYbSLlWMlCrN1tZGdP"
      }
    },
    "updatedBy": {
      "sys": {
        "type": "Link",
        "linkType": "User",
        "id": "75cxRYbSLlWMlCrN1tZGdP"
      }
    },
    "organization": {
      "sys": {
        "type": "Link",
        "linkType": "Organization",
        "id": "75gbeC7tWNTERE55diMpCN"
      }
    }
  },
  "name": "my-template",
  "description": "My Template",
  "versionName": "First Version",
  "versionDescription": "First Version",
  "entities": {
    "contentTypeTemplates": [
      {
        "name": "Blogpost",
        "description": "A blogpost content type",
        "displayField": "title",
        "fields": [
          {
            "id": "title",
            "name": "title",
            "type": "Text"
          }
        ],
        "id": "blogpost"
      }
    ],
    "editorInterfaceTemplates": [
      {
        "contentTypeTemplate": {
          "sys": {
            "id": "blogpost",
            "linkType": "ContentTypeTemplate",
            "type": "Link"
          }
        },
        "controls": [
          {
            "fieldId": "title",
            "widgetId": "urlEditor",
            "widgetNamespace": "builtin",
            "settings": {
              "helpText": "help text"
            }
          }
        ]
      }
    ]
  }
}
  ]
}

User Management API

Introduction

Basic API information

Authentication

Pagination

Example Usage

Request Parameters

Response Attributes

Sorting Results

Example Usage

Including Related Resources

Example Usage

Request

Response

Request

Response

Additional Notes

Searching Multiple Attributes

Example Usage

Filtering Results

Example Usage

Operators

Reference

Organization Memberships

Get all organization memberships

Query Parameters

Filter Parameters

Response

Get a single organization membership

Response

Create an organization membership

Update a single organization membership

Request Body

Response

Delete a single organization membership

Response

Invitations

Create an invitation (alpha)

Request Body

Response

Get a single invitation (alpha)

Response

Delete an invitation

Teams

Get all teams for an organization

Query Parameters

Response

Get all teams for a space

Query Parameters

Response

Get a single team

Response

Create a team

Request Body

Response

Update a single team

Request Body

Response

Delete a single team

Response

Team Memberships

Get all team memberships in a team

Query Parameters

Response

Get all team memberships in an organization

Query Parameters

Filter Parameters

Response

Get a single team membership

Response

Create a team membership

Request Body

Response

Delete a single team membership

Response

Space Memberships

Get all space memberships in a space

Query Parameters

Response

Get all space memberships in an organization