openapi: 3.0.0
info:
  title: Webex Admin Address Book Identity Organization 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: Identity Organization
paths:
  /identity/organizations/{orgId}:
    get:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrgResponse'
              example:
                schemas:
                - urn:cisco:codev:identity:organization:core:1.0
                id: 82adacf4-453f-4e2b-a406-2939fddcaad2
                displayName: Acme, Inc.
                meta:
                  created: '2021-05-13T15:51:09.736Z'
                  lastModified: '2024-05-16T12:25:16.739Z'
                  version: W/"67863103533"
        '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 an organization
      operationId: Get an organization
      description: '<br/>


        **Authorization**


        OAuth token rendered by identity broker.


        <br/>


        One of the following OAuth scopes is required:


        - `identity:organizations_rw`


        - `identity:organizations_read`


        <br/>'
      tags:
      - Identity Organization
      parameters:
      - name: orgId
        in: path
        description: Webex Identity assigned organization identifier.
        required: true
        example: 82adacf4-453f-4e2b-a406-2939fddcaad2
        schema:
          type: string
    patch:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOrgResponse'
              example:
                schemas:
                - urn:cisco:codev:identity:organization:core:1.0
                id: 82adacf4-453f-4e2b-a406-2939fddcaad2
                displayName: Acme_New, Inc.
                preferredLanguage: en_US
                meta:
                  created: '2021-05-13T15:51:09.736Z'
                  lastModified: '2024-05-20T12:25:16.739Z'
                  version: W/"67863100894"
        '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: Update an organization
      operationId: Update an organization
      description: '<br/>


        **Authorization**


        OAuth token rendered by identity broker.


        <br/>


        One of the following OAuth scopes is required:


        - `identity:organizations_rw`


        <br/>


        The following administrators can use this API:


        - `id_full_admin`


        <br/>


        **Usage**:


        1. Input JSON must contain schema: "urn:cisco:codev:identity:organization:core:1.0".'
      tags:
      - Identity Organization
      parameters:
      - name: orgId
        in: path
        description: Webex Identity assigned organization identifier.
        required: true
        example: 82adacf4-453f-4e2b-a406-2939fddcaad2
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              schemas:
              - urn:cisco:codev:identity:organization:core:1.0
              displayName: Acme_New, Inc.
              preferredLanguage: en_US
            schema:
              $ref: '#/components/schemas/updateOrgObject'
  /identity/organizations/{orgId}/users/{userId}/actions/generateOtp:
    post:
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateOtp'
              example:
                oneTimePassword: '283489'
                expiresIn: 604800
        '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: Generate OTP
      operationId: Generate OTP
      description: 'This API allows an admin to generate a One-Time Password (OTP) for user accounts with `userNameType` set as `partner-upn`. The OTP is used by users to log in to any Webex application, whereupon they are asked to change their password.

        The OTP generated by this API has a default length of 6 digits and expires in 7 days.


        Several OTPs can be active for the same user. When the user successfully uses an OTP, all other OTPs are automatically revoked.


        The creation of OTPs is logged in the [Admin Audit Events](https://developer.webex.com/docs/api/v1/admin-audit-events).


        **Possible Error:**


        - 403: The request was forbidden. OTP generation is restricted to users with a `userNameType` of `partner-upn`. This error occurs if the user does not meet the required criteria for OTP generation.


        **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:one_time_password`

        or


        - `Identity:Config`


        **Administrator Roles:**


        The following administrators have permission to use this API:


        - `Org Full Admin`: Can generate OTPs for non-email-type users in their organization.


        - `Partner Full Admin`: Can generate OTPs for User/Machine Accounts in Customer Orgs.


        - `Org User Admin`: Can generate OTPs for User/Machine Accounts within their organization.'
      tags:
      - Identity Organization
      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
      - name: userId
        in: path
        description: The Common Identity-assigned user identifier for an existing user (`entryUUID`).
        required: true
        example: 73e0e4f2-66f6-417a-b074-d473ed537f58
        schema:
          type: string
components:
  schemas:
    updateOrgObject:
      type: object
      required:
      - schemas
      - displayName
      properties:
        schemas:
          type: array
          items:
            type: string
            example: urn:cisco:codev:identity:organization:core:1.0
          description: Input JSON schemas.
        displayName:
          type: string
          example: Acme_New, Inc.
          description: New full name of the organization.
        preferredLanguage:
          type: string
          example: en_US
          description: It is the default preferredLanguage for user creation in this org. It is set in ISO639 format.
    GenerateOtp:
      type: object
      required:
      - oneTimePassword
      - expiresIn
      properties:
        oneTimePassword:
          type: string
          example: '283489'
          description: The One-Time Password generated for the user.
        expiresIn:
          type: number
          example: 604800
          description: 'The expiration time for the OTP in seconds (default: 7 days).'
    metaObject:
      type: object
      required:
      - created
      - lastModified
      - version
      properties:
        created:
          type: string
          example: '"2021-05-13T15:51:09.736Z"'
          description: The date and time the organization was created.
        lastModified:
          type: string
          example: '2024-05-16T12:25:16.739Z'
          description: The last modification time of the organization.
        version:
          type: string
          example: W/\"67863103533\"
          description: The version information of the organization.
    GetOrgResponse:
      type: object
      required:
      - schemas
      - id
      - displayName
      properties:
        schemas:
          type: array
          items:
            type: string
            example: urn:cisco:codev:identity:organization:core:1.0
          description: Output JSON schemas.
        id:
          type: string
          example: 82adacf4-453f-4e2b-a406-2939fddcaad2
          description: Webex Identity assigned organization identifier.
        displayName:
          type: string
          example: Acme, Inc.
          description: Full name of the organization.
        preferredLanguage:
          type: string
          example: en_US
          description: It is the default preferredLanguage for user creation in this org. It is set in ISO639 format.
        meta:
          $ref: '#/components/schemas/metaObject'
          description: Meta data information of 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