Add an email domain to an organization

Adds an email domain. People only join through it once the domain is verified.

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
organizationIdstringRequired

A unique entity identifier

Pattern: ^[a-zA-Z0-9_-]+$
Body
domainstring · max: 253Required
Responses
201

Domain added

application/json

An email domain of an organization.

objectstring · enumRequired

The object type, which is always "organization-domain"

Possible values:
domainstringRequired

The email domain, such as "example.com"

statusstring · enumRequired

Verification status of the domain. "legacy" is a domain added before verification existed: it keeps letting people join automatically without being verified.

Possible values:
statusDescriptionstringOptional

Why the last verification failed

autoJoinEnabledbooleanRequired

Whether people with an email on the domain join the organization automatically

defaultRoleone ofRequired

Role given to people who join through the domain. "default" uses the organization's default role, and "guest" adds them as guests.

string · enumOptional

"The role of a member in an organization. "admin": Can administrate the content: create, delete spaces, ... "create": Can create content. "review": Can review content. "edit": Can edit the content (live or change requests). "comment": Can access the content and its discussions. "read": Can access the content, but cannot update it in any way.

Possible values:
defaultTeamstringOptional

ID of the team that people joining through the domain are added to

verifiedAtstring · date-timeOptional

Date the domain was verified

createdAtstring · date-timeRequired

Date the domain was added

post/orgs/{organizationId}/domains
POST /v1/orgs/{organizationId}/domains HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "domain": "text"
}
{
  "object": "organization-domain",
  "domain": "text",
  "status": "legacy",
  "statusDescription": "text",
  "verificationRecord": {
    "type": "TXT",
    "name": "text",
    "value": "text"
  },
  "autoJoinEnabled": true,
  "defaultRole": "admin",
  "defaultTeam": "text",
  "verifiedAt": "2026-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "urls": {
    "location": "https://example.com"
  }
}

Last updated

Was this helpful?

Powered by GitBook