Organization
Organization
An organization is the top level of a Contentstack account. It holds stacks, users and teams. The Organization class works with organizations through the Content Management API (CMA). Use this class to
- list the organizations of the logged-in user, or read one organization
- list the stacks and the roles of an organization
- invite users, list and resend invitations, and transfer the ownership
- reach the teams of the organization
Call the organization method of the ContentstackClient class to get an object.
Instance State
- Call client.organization() without a UID to work with every organization of the user, with fetchAll.
- Call client.organization('<ORGANIZATION_UID>') to work with one organization, for example fetch and stacks.
- Each form has only its own methods. fetch is undefined on client.organization(), and fetchAll is undefined on client.organization('<ORGANIZATION_UID>'), so calling the wrong one throws TypeError.
- The Organization objects that fetch and fetchAll return have the same methods as client.organization('<ORGANIZATION_UID>').
Warning client.organization('') returns the single-organization form with an empty UID, so every request goes to a path without an organization UID. Check the UID before you build the object.
Class-Level Notes
Authentication.
- Organization requests do not belong to a stack. Create the client with an authtoken, as contentstack.client({ authtoken: '<AUTHTOKEN>' }), or call client.login first. A client with an Open Authorization (OAuth) token also works.
Headers.
- This class has no header methods. Organization requests send only the headers of the client.
Rate limiting and retry.
- This SDK automatically retries on 429 with configurable delay and attempt limits.
Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Remove users from an organization | No | The SDK has no method for it |
| Read the audit log of an organization | No | The AuditLog class reads the audit log of one stack |
| Change a role from the result of roles | No | Those roles carry no stack API key. Use stack.role('<ROLE_UID>') |
Method Index
Work with every organization. Available on client.organization().
| Method Name | Returns | Description |
|---|---|---|
| fetchAll | The organizations of the user. | Lists the organizations of the user. |
Read one organization. Available on client.organization('<ORGANIZATION_UID>').
| Method Name | Returns | Description |
|---|---|---|
| fetch | The requested organization. | Retrieves one organization. |
| stacks | The stacks of the organization. | Lists the stacks of the organization. |
| roles | The roles of the organization. | Lists the roles of the organization. |
Manage users and ownership. Available on client.organization('<ORGANIZATION_UID>').
| Method Name | Returns | Description |
|---|---|---|
| addUser | The sent invitations, as User objects. | Invites users to the organization. |
| getInvitations | The invitations of the organization, as User objects. | Lists the organization invitations. |
| resendInvitation | The API response with a notice. | Resends one pending invitation. |
| transferOwnership | The API response with a notice. | Starts an ownership transfer. |
Reach the teams. Available on client.organization('<ORGANIZATION_UID>').
| Method Name | Returns | Description |
|---|---|---|
| teams | A new teams object. | Returns a Teams object. |
Class-Level Snippet
The snippet below reads one organization and lists the names of its stacks.
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organization = await client.organization('<ORGANIZATION_UID>').fetch()
const stacks = await organization.stacks({ include_count: true })
console.log(organization.name, stacks.count)
for (const stack of stacks.items) {
console.log(stack.api_key, stack.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the Organization class has its own section below, with its parameters, validation rules, behavior, and examples.
addUser
addUser sends invitations that add users to the organization, with product roles and, optionally, stack roles.
| Name | Type | Description |
|---|---|---|
| data (required) | OrganizationInvite | Users to invite and the roles to give them. |
| data.users (required) | object | Maps each email to product role UIDs. |
| data.stacks | object | Maps each email to stack API keys and stack role UIDs. |
Returns: Promise<ContentstackCollection>. The sent invitations, as User objects.
Validation
- There is no client-side validation. addUser sends data as given and does not check the emails or role UIDs.
- addUser exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- Only the owner or an admin of the organization can add users, as the Add users to Organization request in the Content Management API reference states.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/organizations/{organization_uid}/share with the body { share: { users, stacks } }, as the Add users to Organization request in the Content Management API reference describes. The SDK wraps data in the share key.
- data.users has the shape { '<email>': ['<product role UID>'] }. Read the product role UIDs with the roles method.
- data.stacks has the shape { '<email>': { '<stack API key>': ['<stack role UID>'] } }. Read the stack role UIDs with the Role fetchAll method.
- Resolves to a ContentstackCollection. Its items array holds one User object per invitation in the response, and notice holds the message of the API.
Example
Basic usage: invite a user with a product role
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const result = await client.organization('<ORGANIZATION_UID>').addUser({
users: { '<COLLABORATOR_EMAIL>': ['<ROLE_UID>'] }
})
console.log(result.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: invite a user to the organization and to one stack
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const data = {
// Product role UIDs, from organization.roles()
users: { '<COLLABORATOR_EMAIL>': ['<ROLE_UID>'] },
// Stack role UIDs, from stack.role().fetchAll()
stacks: { '<COLLABORATOR_EMAIL>': { '<API_KEY>': ['<ROLE_UID>'] } }
}
try {
const result = await client.organization('<ORGANIZATION_UID>').addUser(data)
for (const invitation of result.items) {
console.log(invitation.uid, invitation.email)
}
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the organization whose UID you passed to client.organization('<ORGANIZATION_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.include_plan | boolean | Adds the plan of the organization. |
Returns: Promise<Organization>. The requested organization.
Validation
- There is no client-side validation.
- fetch exists only on client.organization('<ORGANIZATION_UID>'). On client.organization() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid} with every key of param as a query parameter, as the Get a single Organization request in the Content Management API reference describes.
- Resolves to a new Organization object that holds the organization fields, with the methods of client.organization('<ORGANIZATION_UID>'). The object you called fetch on does not change.
Example
Basic usage: read one organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organization = await client.organization('<ORGANIZATION_UID>').fetch()
console.log(organization.uid, organization.name)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read the plan of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organization = await client.organization('<ORGANIZATION_UID>').fetch({ include_plan: true })
console.log(organization.name, organization.plan)
} catch (error) {
console.error(error.errorMessage)
}fetchAll
fetchAll retrieves the organizations of the logged-in user, in order of creation.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.limit | number | Maximum number of organizations to return. |
| param.skip | number | Number of organizations to skip. |
| param.asc | string | Field to sort by, in ascending order. |
| param.desc | string | Field to sort by, in descending order. |
| param.include_count | boolean | Adds the total number of organizations. |
| param.typeahead | string | Text to match against organization names. |
Returns: Promise<ContentstackCollection>. The organizations of the user.
Validation
- There is no client-side validation.
- fetchAll exists only on client.organization(). On client.organization('<ORGANIZATION_UID>') it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations with every key of param as a query parameter, as the Get all Organizations request in the Content Management API reference describes.
- Resolves to a ContentstackCollection. Its items array holds one Organization object per organization, each with the methods of client.organization('<ORGANIZATION_UID>').
- fetchAll makes one request and does not page through the results. Use limit and skip to read the next page.
Example
Basic usage: list the organizations of the user
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organizations = await client.organization().fetchAll()
for (const organization of organizations.items) {
console.log(organization.uid, organization.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: search by name and sort the second page
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organizations = await client.organization().fetchAll({
limit: 10,
skip: 10,
asc: 'name',
include_count: true,
typeahead: 'Marketing'
})
console.log(organizations.count)
} catch (error) {
console.error(error.errorMessage)
}Edge case: sort in descending order
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const organizations = await client.organization().fetchAll({ desc: 'created_at' })
console.log(organizations.items.map((organization) => organization.name))
} catch (error) {
console.error(error.errorMessage)
}getInvitations
getInvitations retrieves the invitations of the organization, including the ones that users have not accepted yet.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.limit | number | Maximum number of invitations to return. |
| param.skip | number | Number of invitations to skip. |
| param.asc | string | Field to sort by, in ascending order. |
| param.desc | string | Field to sort by, in descending order. |
| param.include_count | boolean | Adds the total number of invitations. |
| param.include_roles | boolean | Adds the roles of each invitation. |
| param.include_invited_by | boolean | Adds the user who sent each invitation. |
| param.include_user_details | boolean | Adds the details of each invited user. |
| param.typeahead | string | Text to match against the invitations. |
Returns: Promise<ContentstackCollection>. The invitations of the organization, as User objects.
Validation
- There is no client-side validation.
- getInvitations exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/share with every key of param as a query parameter, as the Get all Organization invitations request in the Content Management API reference describes.
- Resolves to a ContentstackCollection. Its items array holds one User object per invitation. The uid of an item is the invitation UID that resendInvitation takes.
- getInvitations makes one request and does not page through the results. Use limit and skip to read the next page.
Example
Basic usage: list the invitations of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const invitations = await client.organization('<ORGANIZATION_UID>').getInvitations()
for (const invitation of invitations.items) {
console.log(invitation.uid, invitation.email)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: search the invitations with roles, sender and user details
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const invitations = await client.organization('<ORGANIZATION_UID>').getInvitations({
limit: 20,
skip: 0,
asc: 'email',
include_count: true,
include_roles: true,
include_invited_by: true,
include_user_details: true,
typeahead: 'example.com'
})
console.log(invitations.count)
} catch (error) {
console.error(error.errorMessage)
}Edge case: list the newest invitations first
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const invitations = await client.organization('<ORGANIZATION_UID>').getInvitations({ desc: 'created_at' })
console.log(invitations.items.map((invitation) => invitation.email))
} catch (error) {
console.error(error.errorMessage)
}resendInvitation
resendInvitation sends a pending organization invitation again, to a user who has not accepted it yet.
| Name | Type | Description |
|---|---|---|
| invitationUid (required) | string | UID of the pending invitation. |
Returns: Promise<Response>. The API response with a notice.
Known issue resendInvitation leaves the share segment out of the request path, so the API can reject the request. Pass the invitation UID as share/<SHARE_UID> until a fix ships.
Validation
- There is no client-side validation. A missing invitationUid puts undefined in the request path.
- resendInvitation exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- Only the owner or an admin of the organization can resend an invitation, as the Resend pending Organization invitation request in the Content Management API reference states.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/{invitationUid}/resend_invitation.
- The Resend pending Organization invitation request in the Content Management API reference uses GET /v3/organizations/{organization_uid}/share/{share_uid}/resend_invitation. With share/<SHARE_UID> as the argument, the SDK sends that path.
- Read the invitation UIDs with the getInvitations method.
- Resolves to the response body, which carries notice.
Example
Basic usage: resend a pending invitation
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
// The share/ prefix sends the path that the API documents
const response = await client.organization('<ORGANIZATION_UID>').resendInvitation('share/<SHARE_UID>')
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Edge case: resend the first invitation from the list
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const organization = client.organization('<ORGANIZATION_UID>')
try {
const invitations = await organization.getInvitations()
if (invitations.items.length > 0) {
const response = await organization.resendInvitation(`share/${invitations.items[0].uid}`)
console.log(response.notice)
}
} catch (error) {
console.error(error.errorMessage)
}roles
roles retrieves the roles of the organization, which set what each member can do in it.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.limit | number | Maximum number of roles to return. |
| param.skip | number | Number of roles to skip. |
| param.asc | string | Field to sort by, in ascending order. |
| param.desc | string | Field to sort by, in descending order. |
| param.include_count | boolean | Adds the total number of roles. |
| param.include_stack_roles | boolean | Adds the stack details of each role. |
Returns: Promise<ContentstackCollection>. The roles of the organization.
Validation
- There is no client-side validation.
- roles exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/roles with every key of param as a query parameter, as the Get all roles in an Organization request in the Content Management API reference describes.
- Resolves to a ContentstackCollection. Its items array holds one Role object per role.
- The items carry no stack API key, so they have no fetch, update or delete. Read their fields only.
- Pass the uid of a product role to addUser to invite a user with that role.
Example
Basic usage: list the roles of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const roles = await client.organization('<ORGANIZATION_UID>').roles()
for (const role of roles.items) {
console.log(role.uid, role.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: include stack details and a count
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const roles = await client.organization('<ORGANIZATION_UID>').roles({
limit: 50,
skip: 0,
asc: 'name',
include_count: true,
include_stack_roles: true
})
console.log(roles.count)
} catch (error) {
console.error(error.errorMessage)
}Edge case: sort the roles in descending order
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const roles = await client.organization('<ORGANIZATION_UID>').roles({ desc: 'name' })
console.log(roles.items.map((role) => role.name))
} catch (error) {
console.error(error.errorMessage)
}stacks
stacks retrieves the stacks of the organization.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
| param.limit | number | Maximum number of stacks to return. |
| param.skip | number | Number of stacks to skip. |
| param.asc | string | Field to sort by, in ascending order. |
| param.desc | string | Field to sort by, in descending order. |
| param.include_count | boolean | Adds the total number of stacks. |
| param.typeahead | string | Text to match against stack names. |
Returns: Promise<ContentstackCollection>. The stacks of the organization.
Validation
- There is no client-side validation.
- stacks exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends GET /v3/organizations/{organization_uid}/stacks with every key of param as a query parameter, as the Get all stacks in an Organization request in the Content Management API reference describes.
- Resolves to a ContentstackCollection. Its items array holds one Stack object per stack. Each item carries its api_key and sends requests with the credentials of the client.
- stacks makes one request and does not page through the results. Use limit and skip to read the next page.
Example
Basic usage: list the stacks of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const stacks = await client.organization('<ORGANIZATION_UID>').stacks()
for (const stack of stacks.items) {
console.log(stack.api_key, stack.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: search by name and sort the first page
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const stacks = await client.organization('<ORGANIZATION_UID>').stacks({
limit: 25,
skip: 0,
asc: 'name',
include_count: true,
typeahead: 'blog'
})
console.log(stacks.count, stacks.items.map((stack) => stack.name))
} catch (error) {
console.error(error.errorMessage)
}Edge case: list the newest stacks first
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const stacks = await client.organization('<ORGANIZATION_UID>').stacks({ desc: 'created_at', limit: 5 })
console.log(stacks.items.map((stack) => stack.name))
} catch (error) {
console.error(error.errorMessage)
}teams
teams returns a Teams object for the teams of the organization. It sends no request.
| Name | Type | Description |
|---|---|---|
| teamUid | string | UID of one team. |
Returns: Teams. A new teams object.
Known issue After teams('<TEAM_UID>'), a later teams() call on the same organization object returns that team instead of the collection, without create or fetchAll. Start each chain from a new client.organization('<ORGANIZATION_UID>') call.
Validation
- There is no client-side validation.
- teams exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- An invalid value surfaces as a rejected promise from the request method you call next.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Client-side only. teams builds a Teams object with the organization UID.
- Without teamUid, the object has create and fetchAll.
- With teamUid, the object has fetch, update, delete, teamUsers and stackRoleMappings.
- An empty string counts as no UID and returns the collection form.
Example
Basic usage: list the teams of an organization
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const teams = await client.organization('<ORGANIZATION_UID>').teams().fetchAll()
for (const team of teams.items) {
console.log(team.uid, team.name)
}
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: read one team
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').fetch()
console.log(team.name, team.organizationRole)
} catch (error) {
console.error(error.errorMessage)
}Edge case: switch between one team and the collection
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const team = await client.organization('<ORGANIZATION_UID>').teams('<TEAM_UID>').fetch()
// Build a new organization object for the collection form
const teams = await client.organization('<ORGANIZATION_UID>').teams().fetchAll()
console.log(team.name, teams.items.length)
} catch (error) {
console.error(error.errorMessage)
}transferOwnership
transferOwnership starts the transfer of the organization to another user, by email invitation.
| Name | Type | Description |
|---|---|---|
| email (required) | string | Email address of the new owner. |
Returns: Promise<Response>. The API response with a notice.
Warning When the new owner accepts the invitation, the ownership of the organization moves to that user. The SDK has no method that cancels or reverses the transfer.
Validation
- There is no client-side validation. transferOwnership sends email as given and does not check its format.
- transferOwnership exists only on client.organization('<ORGANIZATION_UID>') and on the Organization objects that fetch and fetchAll return. On client.organization() it is undefined, and calling it throws TypeError.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends POST /v3/organizations/{organization_uid}/transfer-ownership with the body { transfer_to: email }, as the Transfer Organization ownership request in the Content Management API reference describes.
- The API emails an invitation to the user. The ownership moves when that user accepts it through the link in the email, not when the request succeeds.
- Resolves to the response body, which carries notice.
Example
Basic usage: transfer an organization to another user
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
try {
const response = await client.organization('<ORGANIZATION_UID>').transferOwnership('<NEW_OWNER_EMAIL>')
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}