openapi: 3.0.0 info: title: Webex Admin Address Book API - Domain Management API version: 1.0.0 description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling. tags: - name: API - Domain Management paths: /identity/organizations/{orgId}/actions/getDomainVerificationToken: post: responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/DomainVerificationToken' example: domain: cisco.com token: f5014515-6559-4a30-9d68-0deb028f27b7 verificationMethod: DNS_TXT url: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/GetToken/invoke '400': description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.' '401': description: 'Unauthorized: Authentication credentials were missing or incorrect.' '403': description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.' '404': description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.' '405': description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.' '409': description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.' '410': description: 'Gone: The requested resource is no longer available.' '415': description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.' '423': description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.' '428': description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.' '429': description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.' '500': description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).' '502': description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.' '503': description: 'Service Unavailable: Server is overloaded with requests. Try again later.' '504': description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.' summary: Get Domain Verification Token operationId: Get Domain Verification Token description: 'This endpoint helps generate a token for a given domain within the specified organization. The user needs to add this token as a ''TXT'' record to the DNS server. **Possible Error:** - 409: The request encountered a resource conflict. This error occurs if the domain is either claimed by another organization or by the same organization. **Authorization:** An ''OAuth'' token issued by the ''Identity Broker'' is required to access this endpoint. The token must include one of the following scopes: - `Identity:Organization` - `identity:organizations_rw` **Administrator Roles:** The following administrators can use this API: - `id_full_admin`' tags: - API - Domain Management parameters: - name: orgId in: path description: The Webex Identity-assigned organization identifier for a user's organization. required: true example: bf732c85-68ca-4867-94e4-937286ad2fd4 schema: type: string requestBody: content: application/json: example: domain: cisco.com schema: $ref: '#/components/schemas/PostDomainVerificationToken' /identity/organizations/{orgId}/actions/verifyDomain: post: responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/DomainVerification' example: verifiedDomains: - cisco.com - webex.com claimedDomains: - cisco.com - webex.com url: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/Verify/invoke '400': description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.' '401': description: 'Unauthorized: Authentication credentials were missing or incorrect.' '403': description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.' '404': description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.' '405': description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.' '409': description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.' '410': description: 'Gone: The requested resource is no longer available.' '415': description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.' '423': description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.' '428': description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.' '429': description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.' '500': description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).' '502': description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.' '503': description: 'Service Unavailable: Server is overloaded with requests. Try again later.' '504': description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.' summary: Verify Domain operationId: Verify Domain description: 'This endpoint helps verify a given domain within the specified organization. This API verifies domain ownership by looking up and validating the ''TXT'' record for the domain. Once verified, domain enforcement will be applied to the organization. Any users in the organization whose email domain doesn''t match one of the verified domains will be marked as transient. If you want to verify and claim the domain, just set the ''claimDomain'' parameter to true. By default, it''s set to false, which will only verify the domain. **Possible Errors:** - 400: The request was a Bad Request. The domain can''t be verified. This error happens if the user didn''t request a token before trying to verify the domain. - 409: The request resulted in a resource conflict. This error occurs if the domain has already been claimed by another organization. **Authorization:** An ''OAuth'' token issued by the ''Identity Broker'' is required to access this endpoint. The token must include one of the following scopes: - `Identity:Organization` - `identity:organizations_rw` **Administrator Roles:** The following administrators can use this API: - `id_full_admin`' tags: - API - Domain Management parameters: - name: orgId in: path description: The Webex Identity-assigned organization identifier for a user's organization. required: true example: bf732c85-68ca-4867-94e4-937286ad2fd4 schema: type: string requestBody: content: application/json: example: domain: cisco.com claimDomain: false reserveDomain: false schema: $ref: '#/components/schemas/PostDomainVerification' /identity/organizations/{orgId}/actions/claimDomain: post: responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ClaimDomain' example: data: - domain: cisco.com url: https://identity.webex.com/organizations/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/domains/ZXhhbXBsZTMuY29t '400': description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.' '401': description: 'Unauthorized: Authentication credentials were missing or incorrect.' '403': description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.' '404': description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.' '405': description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.' '409': description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.' '410': description: 'Gone: The requested resource is no longer available.' '415': description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.' '423': description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.' '428': description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.' '429': description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.' '500': description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).' '502': description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.' '503': description: 'Service Unavailable: Server is overloaded with requests. Try again later.' '504': description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.' summary: Claim Domain operationId: Claim Domain description: 'This endpoint helps claim the given domain within the specified organization. The domain needs to be verified before it can be claimed. **Note** There''s an organization-level boolean flag called ''enforceVerifiedDomains''. If this flag is set to false, we won''t put any user in the organization into a transient state when verifying or claiming a domain. Customers can still create users within the organization who don''t use the verified domains as their email. However, if the flag is set to true, all users in the organization must use one of the verified domains as their email. This flag defines whether the organization enforces user email verification within the organization. If set to true, all users inside the organization must use one of the verified domains. This flag is effective only after the admin has verified at least one email domain. **Possible Error:** - 400: The request was a Bad Request. This error occurs if the domain is not verified. **Authorization:** An ''OAuth'' token issued by the ''Identity Broker'' is required to access this endpoint. The token must include one of the following scopes: - `Identity:Organization` - `identity:organizations_rw` **Administrator Roles:** The following administrators can use this API: - `id_full_admin`' tags: - API - Domain Management parameters: - name: orgId in: path description: The Webex Identity-assigned organization identifier for a user's organization. required: true example: bf732c85-68ca-4867-94e4-937286ad2fd4 schema: type: string requestBody: content: application/json: example: data: - domain: cisco.com forceDomainClaim: true claimDomainOnly: false schema: $ref: '#/components/schemas/PostClaimDomain' /identity/organizations/{orgId}/actions/unverifyDomain: post: responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/DomainUnverification' example: verifiedDomains: - cisco.com - webex.com claimedDomains: - cisco.com - webex.com url: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/Unverify/invoke '400': description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.' '401': description: 'Unauthorized: Authentication credentials were missing or incorrect.' '403': description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.' '404': description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.' '405': description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.' '409': description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.' '410': description: 'Gone: The requested resource is no longer available.' '415': description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.' '423': description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.' '428': description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.' '429': description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.' '500': description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).' '502': description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.' '503': description: 'Service Unavailable: Server is overloaded with requests. Try again later.' '504': description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.' summary: Unverify Domain operationId: Unverify Domain description: 'After you unclaim the domain, it will still be verified. Domain enforcement will still apply to the organization. The unverify endpoint helps to remove the domain ownership verification for the organization. **Possible Error:** - 400: The request was a Bad Request. The domain cannot be unverified. This error occurs if the domain is still claimed. - 404: The request was Not Found. This error occurs if the domain is not associated with the organization. **Authorization:** An ''OAuth'' token issued by the ''Identity Broker'' is required to access this endpoint. The token must include one of the following scopes: - `Identity:Organization` - `identity:organizations_rw` **Administrator Roles:** The following administrators can use this API: - `id_full_admin`' tags: - API - Domain Management parameters: - name: orgId in: path description: The Webex Identity-assigned organization identifier for a user's organization. required: true example: bf732c85-68ca-4867-94e4-937286ad2fd4 schema: type: string requestBody: content: application/json: example: domain: abc.com removePending: false schema: $ref: '#/components/schemas/PostDomainUnverification' /identity/organizations/{orgId}/actions/unclaimDomain: post: responses: '204': description: No Content headers: {} content: {} '400': description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.' '401': description: 'Unauthorized: Authentication credentials were missing or incorrect.' '403': description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.' '404': description: 'Not Found: The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.' '405': description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.' '409': description: 'Conflict: The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.' '410': description: 'Gone: The requested resource is no longer available.' '415': description: 'Unsupported Media Type: The request was made to a resource without specifying a media type or used a media type that is not supported.' '423': description: 'Locked: The requested resource is temporarily unavailable. A Retry-After header may be present that specifies how many seconds you need to wait before attempting the request again.' '428': description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.' '429': description: 'Too Many Requests: Too many requests have been sent in a given amount of time and the request has been rate limited. A Retry-After header should be present that specifies how many seconds you need to wait before a successful request can be made.' '500': description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).' '502': description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.' '503': description: 'Service Unavailable: Server is overloaded with requests. Try again later.' '504': description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.' summary: Unclaim Domain operationId: Unclaim Domain description: 'This API is used to unclaim a domain for the organization. The domain will remain verified, and domain enforcement will still apply to the given organization. **Possible Error:** - 400: The request was a Bad Request. The domain cannot be unclaimed. This error occurs if the requested parameter is invalid. **Authorization:** An ''OAuth'' token issued by the ''Identity Broker'' is required to access this endpoint. The token must include one of the following scopes: - `Identity:Organization` - `identity:organizations_rw` **Administrator Roles:** The following administrators can use this API: - `id_full_admin`' tags: - API - Domain Management parameters: - name: orgId in: path description: The Webex Identity-assigned organization identifier for a user's organization. required: true example: bf732c85-68ca-4867-94e4-937286ad2fd4 schema: type: string requestBody: content: application/json: example: domain: test.dc-01.com schema: $ref: '#/components/schemas/UnclaimDomain' components: schemas: PostDomainUnverification: type: object required: - domain properties: domain: type: string example: abc.com description: Domain name to be verified. removePending: type: boolean description: Specify whether to remove pending domain. Default is false (backward compatibility). If true, domains will be deleted from pending domain list. PostDomainVerification: type: object required: - domain properties: domain: type: string example: cisco.com description: The domain name to be verified. claimDomain: type: boolean description: A boolean to specify whether the domain needs to be claimed. The default value is false. If false, the domain will be verified but not claimed. reserveDomain: type: boolean description: 'For FedRAMP only: If true, add the domain to the FedRAMP reserved domain list. The default value is false.' UnclaimDomain: type: object required: - domain properties: domain: type: string example: test.dc-01.com description: A claimed domain. DomainUnverification: type: object required: - verifiedDomains - claimedDomains - url properties: verifiedDomains: type: array items: type: string example: cisco.com,webex.com description: A list of verified domains for a given organization. claimedDomains: type: array items: type: string example: cisco.com,webex.com description: A list of claimed domains for a given organization. url: type: string example: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/Unverify/invoke description: Use this URL for unverifying domain ownership and managing the domain lifecycle within the organization. PostDomainVerificationToken: type: object required: - domain properties: domain: type: string example: cisco.com description: A valid domain name. DomainVerificationToken: type: object required: - domain - token - verificationMethod - url properties: domain: type: string example: cisco.com description: The domain name for which the token is generated. token: type: string example: f5014515-6559-4a30-9d68-0deb028f27b7 description: 'A token needs to be added as a TXT record in your domain''s DNS settings. You should add the following string: ''cisco-ci-domain-verification='' as a TXT record in your DNS settings.' verificationMethod: type: string example: DNS_TXT description: 'Domain verification method: Currently, we only support the DNS_TXT method for domain verification.' url: type: string example: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/GetToken/invoke description: Use this URL for retrieving an authentication token needed to interact with the Domain Verification API. ClaimDomain: type: object required: - domain - url properties: domain: type: string example: cisco.com description: A list of verified domains for a given organizations. url: type: string example: https://identity.webex.com/organizations/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/domains/ZXhhbXBsZTMuY29t description: Use this location URL for the domain resource. The resource component of the URL will be the base64 encoded domain name. Domain: type: object required: - domain properties: domain: type: string example: cisco.com description: A valid domain name that is already verified by the organization. PostClaimDomain: type: object properties: data: type: array items: $ref: '#/components/schemas/Domain' description: A List of valid domain name that is already verified by the organization. forceDomainClaim: type: boolean example: true description: Indicate if the domain should be claimed when there are users outside the organization using the same domain. The default is true. claimDomainOnly: type: boolean description: Indicate to just claim the domain only without searching/marking external users as transient. The default is false. DomainVerification: type: object required: - verifiedDomains - claimedDomains - url properties: verifiedDomains: type: array items: type: string example: cisco.com,webex.com description: A list of verified domains for a given organization. claimedDomains: type: array items: type: string example: cisco.com,webex.com description: A list of claimed domains for a given organization. url: type: string example: https://identity.webex.com/organization/bf732c85-68ca-4867-94e4-937286ad2fd4/v1/actions/DomainVerification/Verify/invoke description: Use this URL for verifying domain ownership and managing the domain lifecycle within the organization. securitySchemes: oauth2: flows: authorizationCode: authorizationUrl: / scopes: {} tokenUrl: / type: oauth2 bearer-key: type: http description: e.g. Bearer YOUR_AUTHORIZATION_TOKEN scheme: bearer bearerFormat: JWT bearerAuth: type: oauth2 description: OAuth 2.0 Bearer token authentication flows: authorizationCode: authorizationUrl: https://webexapis.com/v1/authorize tokenUrl: https://webexapis.com/v1/access_token scopes: spark:applications_token: Create access tokens for Service Apps