Adobe Suite Identity Namespace API

openapi: 3.2.0
info:
  title: Identity Service Identity Namespace API
  description: "Delivering relevant digital experiences requires having a complete\nunderstanding of your customer. This is made more difficult when your\ncustomer data is fragmented across disparate systems, causing each\nindividual customer to appear to have multiple \"identities\". Adobe\nExperience Platform Identity Service provides a RESTful API to help you to\ngain a better view of your customers and their behavior. By bridging\nidentities across devices and systems, you are better able to deliver\nimpactful, personal digital experiences in real-time. <br><br>\n\nUse the Identity Service API to manage identities, namespaces, and clusters\nlinked to the Identity Graph. <br><br>\n\n**Related documentation**:\n  * [Identity Service documentation](https://www.adobe.com/go/identity-overview-en)\n\n**Visualize API calls with Postman (a free, third-party software)**:\n  * [Identity Service API Postman collection on GitHub](https://github.com/adobe/experience-platform-postman-samples/blob/master/apis/experience-platform/Identity%20Service.postman_collection.json)\n  * [Video guide for creating the Postman environment](https://video.tv.adobe.com/v/28832)\n  * [Steps for importing environments and collections in Postman](https://learning.getpostman.com/docs/postman/collection_runs/using_environments_in_collection_runs/)\n\n**API paths**:\n  * PLATFORM Gateway URL: https://<span>platform-{REGION}.adobe.io\n    * Information on <code>{REGION}</code> values can be found in the [Identity Service developer guide](https://experienceleague.adobe.com/docs/experience-platform/identity/api/getting-started.html).\n  * Base path for this API: /data/core/\n  * Example of a complete path: https://<span>platform-va7.adobe.io/data/core/identity/cluster/members\n\n**Required headers**:\n  * All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](http://www.adobe.com/go/platform-api-authentication-en).\n  * All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require the header `x-sandbox-name` whose value is the all-lowercase name of the sandbox the operation will take place in (for example, \"prod\"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.\n  * All requests with a payload in the request body (such as POST, PUT, and PATCH calls) must include the header `Content-Type` with a value of `application/json`.\n\n- **API error handling**:\n    - Refer to the Experience Platform API troubleshooting guide for [FAQs](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#faq), [API status codes](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#api-status-codes), and [request header errors](https://experienceleague.adobe.com/docs/experience-platform/landing/troubleshooting.html#request-header-errors).\n"
  version: 1.0.0
servers:
- url: https://{environment}.adobe.io/data/core
  variables:
    environment:
      default: platform
      enum:
      - platform
      - platform-stage
tags:
- name: Identity Namespace
  description: 'Identity namespaces provide context to identity data. Experience Platform

    provides standard namespaces as well as allowing organizations to create

    and manage custom namespaces.

    '
paths:
  /idnamespace/identities:
    get:
      tags:
      - Identity Namespace
      summary: Lists all identity namespaces available for the IMS Organization
      description: 'The

        `https://platform.adobe.io/data/core/idnamespace/orgs/{ORG}/identities`

        endpoint has been deprecated. You may use the `/idnamespace/identities`

        endpoint to accomplish the same task and list all namespaces owned by a

        given organization.

        '
      operationId: getIdNamespaces
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-request-id'
      responses:
        '200':
          description: 'Returns a list of all ID namespaces as an array with individual

            objects containing the details for each namespace.

            '
          x-summary: Success - Namespaces List Retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/listNamespaces'
        '401':
          description: Authentication failure for invalid IMS token.
          x-summary: Unauthorized - Invalid IMS Token
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 401
                  error:
                    type: string
                    example: INVALID_IMS_TOKEN
                  title:
                    type: string
                    example: Namespace Validation
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Authorization failed - Missing product context acp for

                          given IMS token.

                          '
        '500':
          description: Internal server error
          x-summary: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 500
                  title:
                    type: string
                    example: Internal Server Failure.
                  error:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Internal server error occurred. Please try at a later

                          time.

                          '
    post:
      tags:
      - Identity Namespace
      summary: Create a new identity namespace
      operationId: createNamespace
      parameters:
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/content-type'
      requestBody:
        description: "JSON object containing the details of the namespace to be created.\n\n* **name:** **(Required)** A friendly name (or \"Display Name\") for the\nnamespace.  \n\n* **code:** **(Required)** Known as the \"Identity symbol\" in the user\ninterface, the \"code\" is a single word descriptor for the namespace\nbeing created. Must be unique. May contain only letters and numbers.\n\n* **idType:** **(Required)** The \"type\" of namespace being created.\nMust be one of the following values: Cookie, Cross_device, Device,\nEmail, Mobile, Non_people, or Phone.\n\n* **description:** *(Optional)* A description for the namespace. This\nis especially useful when multiple namespaces have been defined for\nyour organization.\n"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/namespaceCreate'
        required: true
      responses:
        '200':
          description: 'Identity namespace created successfully. Returns details of newly

            created identity namespace.

            '
          x-summary: Identity namespace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '400':
          description: Creation of namespace failed because of data-issue.
          x-summary: Invalid request data
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 400
                  description:
                    type: string
                    example: 'Please provide a valid value of idType. Valid values are:

                      [DEVICE, COOKIE, CROSS_DEVICE, PHONE, EMAIL]

                      '
                  title:
                    type: string
                    example: Namespace validation
                  report:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INVALID_REQUEST_PARAMS
        '401':
          description: Authentication failure for invalid IMS token.
          x-summary: Invalid authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 401
                  error:
                    type: string
                    example: INVALID_IMS_TOKEN
                  title:
                    type: string
                    example: Namespace Validation
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Authorization failed - Missing product context acp for

                          given IMS token.

                          '
        '409':
          description: 'Creation of namespace failed because of a conflict in namespace

            code.

            '
          x-summary: Namespace code conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 409
                  title:
                    type: string
                    example: NAMESPACE_CODE_CONFLICT
                  description:
                    type: string
                    example: Namespace code already exists. Please use a different code
                  report:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INTEGRATION_CODE_EXISTS
        '500':
          description: Internal server error
          x-summary: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 500
                  title:
                    type: string
                    example: Internal Server Failure.
                  error:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Internal server error occurred. Please try at a later

                          time

                          '
      x-codegen-request-body-name: body
  /idnamespace/identities/{ID}:
    get:
      tags:
      - Identity Namespace
      summary: Retrieve details of a specific identity namespace by its ID
      description: 'The

        `https://platform.adobe.io/data/core/idnamespace/orgs/{ORG}/identities/{ID}`

        endpoint has been deprecated. You may use the

        `/idnamespace/identities/{ID}` endpoint to accomplish the same task and

        retrieve a specific namespace owned by a given organization.

        '
      operationId: retrieveIdentityNamespace
      parameters:
      - $ref: '#/components/parameters/namespace-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/x-request-id'
      responses:
        '200':
          description: OK
          x-summary: Namespace retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Namespace'
        '401':
          description: Authentication failure for invalid IMS token.
          x-summary: Invalid authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 401
                  error:
                    type: string
                    example: INVALID_IMS_TOKEN
                  title:
                    type: string
                    example: Namespace Validation
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Authorization failed - Missing product context acp for

                          given IMS token.

                          '
        '404':
          description: Namespace does not exist or it is not available for the given imsorg
          x-summary: Namespace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 404
                  error:
                    type: string
                    example: NAMESPACE_NOT_FOUND
                  description:
                    type: string
                    example: 'Namespace id not found for given IMS Org

                      09A55EBC5639E6017F000101@AdobeOrg

                      '
                  title:
                    type: string
                    example: Namespace validation
                  report:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NAMESPACE_NOT_FOUND
        '500':
          description: Internal server error
          x-summary: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 500
                  title:
                    type: string
                    example: Internal Server Failure.
                  error:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Internal server error occurred. Please try at a later

                          time

                          '
    put:
      tags:
      - Identity Namespace
      summary: Update specific identity namespace
      operationId: updateIdentityNamespace
      parameters:
      - $ref: '#/components/parameters/namespace-id'
      - $ref: '#/components/parameters/authorization'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
      - $ref: '#/components/parameters/content-type'
      requestBody:
        description: 'A JSON object containing the updated information for the namespace.

          This operation is essentially *replacing* the existing namespace,

          therefore all fields required to define the namespace must be sent in

          the request (with updated values for those attributes being changed).

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/namespaceUpdate'
        required: true
      responses:
        '200':
          description: 'Returns the details of the updated identity namespace. ID should

            match the ID sent in the request path.

            '
          x-summary: Namespace updated successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/updateNamespace'
        '400':
          description: Invalid request to update the namespace.
          x-summary: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 400
                  error:
                    type: string
                    example: INVALID_REQUEST_PARAMS
                  description:
                    type: string
                    example: code and idType are non editable fields
                  title:
                    type: string
                    example: Namespace Validation
                  report:
                    type: object
                    properties:
                      code:
                        type: string
                        example: INVALID_REQUEST_PARAMS
        '401':
          description: Authentication failure for invalid IMS token.
          x-summary: Invalid authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 401
                  error:
                    type: string
                    example: INVALID_IMS_TOKEN
                  title:
                    type: string
                    example: Namespace Validation
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Authorization failed - Missing product context acp for

                          given IMS token.

                          '
        '404':
          description: Namespace does not exist or it is not available for the given imsorg
          x-summary: Namespace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 404
                  error:
                    type: string
                    example: NAMESPACE_NOT_FOUND
                  description:
                    type: string
                    example: 'Namespace id not found for given IMS Org

                      09A55EBC5639E6017F000101@AdobeOrg

                      '
                  title:
                    type: string
                    example: Namespace validation
                  report:
                    type: object
                    properties:
                      code:
                        type: string
                        example: NAMESPACE_NOT_FOUND
        '500':
          description: Internal server error
          x-summary: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    example: '2019-05-10T22:24:54.914Z'
                  type:
                    type: string
                    example: http://ns.adobe.com/adobecloud/problem/namespacevalidation
                  status:
                    type: integer
                    example: 500
                  title:
                    type: string
                    example: Internal Server Failure.
                  error:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                  report:
                    type: object
                    properties:
                      message:
                        type: string
                        example: 'Internal server error occurred. Please try at a later

                          time

                          '
      x-codegen-request-body-name: body
components:
  parameters:
    namespace-id:
      name: ID
      in: path
      description: The numeric value of the "id" field.
      required: true
      schema:
        type: integer
    authorization:
      name: Authorization
      in: header
      description: 'The access token which can be copied from your Experience Platform

        integration, prefixed with "Bearer ". For more information on how to

        obtain this value, visit the [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
    content-type:
      name: Content-Type
      in: header
      description: The type of content being sent in the request. Use 'application/json'.
      required: true
      schema:
        type: string
        default: application/json
    x-request-id:
      name: x-request-id
      in: header
      description: Request id to be used for tracing this request.
      schema:
        type: string
    x-api-key:
      name: x-api-key
      in: header
      description: 'The API key which can be copied from your Experience Platform

        integration. For more information on how to obtain this value, visit the

        [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      in: header
      description: 'The Organization ID which can be copied from your Experience Platform

        integration. For more information on how to obtain this value, visit the

        [authentication

        tutorial](http://www.adobe.com/go/platform-api-authentication-en).

        '
      required: true
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      in: header
      description: 'The the all-lowercase name of the sandbox the operation will take place in. If unspecified, falls back to the default production sandbox (usually "prod"). See the [sandboxes overview](https://adobe.com/go/sandbox-overview-en) for more information.

        '
      schema:
        type: string
        example: prod
  schemas:
    updateNamespace:
      type: object
      properties:
        updateTime:
          type: integer
          format: int64
          example: 1954221412123
        code:
          type: string
          example: New namespce code
        status:
          type: string
          example: ACTIVE
        createTime:
          type: integer
          format: int64
          example: 1572918753626
        description:
          type: string
          example: New description.
        idType:
          type: string
          example: COOKIE
          enum:
          - COOKIE
          - CROSS_DEVICE
          - Device
          - Email
          - MOBILE
          - Non_people
          - Phone
        name:
          type: string
          example: New namespace name
        id:
          type: integer
          format: int64
          example: 10018776
        custom:
          type: boolean
          example: true
    namespaceUpdate:
      required:
      - code
      - idType
      - name
      type: object
      properties:
        name:
          type: string
          example: New namespace name
        code:
          type: string
          example: New namespace code
        idType:
          type: string
          example: COOKIE
          enum:
          - COOKIE
          - CROSS_DEVICE
          - Device
          - Email
          - MOBILE
          - Non_people
          - Phone
        description:
          type: string
          example: New description.
    namespaceCreate:
      required:
      - code
      - idType
      - name
      type: object
      properties:
        name:
          type: string
          example: Loyalty Member ID
        code:
          type: string
          example: Loyalty
        idType:
          type: string
          example: Email
          enum:
          - Cookie
          - Cross_device
          - Device
          - Email
          - Mobile
          - Non_people
          - Phone
        description:
          type: string
          example: The email address associated with loyalty program membership.
    listNamespaces:
      type: array
      items:
        type: object
        properties:
          updateTime:
            type: integer
            format: int64
            example: 1572918753626
          code:
            type: string
            example: Email
          status:
            type: string
            example: ACTIVE
          createTime:
            type: integer
            format: int64
            example: 1572918753626
          description:
            type: string
            example: Email
          idType:
            type: string
            example: CROSS_DEVICE
            enum:
            - COOKIE
            - CROSS_DEVICE
            - Device
            - Email
            - MOBILE
            - Non_people
            - Phone
          name:
            type: string
            example: Loyalty Member ID
          id:
            type: integer
            format: int64
            example: 6
          custom:
            type: boolean
            example: false
    Namespace:
      type: object
      properties:
        updateTime:
          type: integer
          format: int64
          example: 1572918753626
        code:
          type: string
          example: Loyalty
        status:
          type: string
          example: ACTIVE
        createTime:
          type: integer
          format: int64
          example: 1572918753626
        description:
          type: string
          example: The email address associated with loyalty program membership.
        idType:
          type: string
          example: Email
          enum:
          - Cookie
          - Cross_device
          - Device
          - Email
          - Mobile
          - Non_people
          - Phone
        name:
          type: string
          example: Loyalty Member ID
        id:
          type: integer
          format: int64
          example: 10018776
        custom:
          type: boolean
          example: true
x-original-swagger-version: '2.0'