Amazon IoT Core Principals API

openapi: 3.2.0
info:
  title: Amazon Iot Core Principals API
  x-refined-note:
  - x-apiClientRegistration differs across the merged source definitions and was not carried
  - x-apisguru-categories differs across the merged source definitions and was not carried
  - x-aws-signingName differs across the merged source definitions and was not carried
  - x-logo differs across the merged source definitions and was not carried
  - x-origin differs across the merged source definitions and was not carried
  - x-preferred differs across the merged source definitions and was not carried
  - x-providerName differs across the merged source definitions and was not carried
  - x-release differs across the merged source definitions and was not carried
  - x-serviceName differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Principals across 2 of this provider''s published API definitions: amazon-iot-core-openapi-original.yml, amazon-iot-core-principals-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://iot.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The AWS IoT multi-region endpoint
- url: https://iot.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The AWS IoT multi-region endpoint
- url: http://iot.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The AWS IoT endpoint for China (Beijing) and China (Ningxia)
- url: https://iot.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The AWS IoT endpoint for China (Beijing) and China (Ningxia)
tags:
- name: Principals
paths:
  /principals/things#x-amzn-principal:
    parameters:
    - $ref: '#/components/parameters/X-Amz-Content-Sha256'
    - $ref: '#/components/parameters/X-Amz-Date'
    - $ref: '#/components/parameters/X-Amz-Algorithm'
    - $ref: '#/components/parameters/X-Amz-Credential'
    - $ref: '#/components/parameters/X-Amz-Security-Token'
    - $ref: '#/components/parameters/X-Amz-Signature'
    - $ref: '#/components/parameters/X-Amz-SignedHeaders'
    get:
      operationId: ListPrincipalThings
      description: 'Lists the things associated with the specified principal. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities.


        Requires permission to access the ListPrincipalThings action.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPrincipalThingsResponse'
        '480':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '481':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
        '482':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException'
        '483':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException'
        '484':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '485':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
      parameters:
      - name: nextToken
        in: query
        required: false
        description: To retrieve the next set of results, the <code>nextToken</code> value from a previous response; otherwise <b>null</b> to receive the first set of results.
        schema:
          type: string
      - name: maxResults
        in: query
        required: false
        description: The maximum number of results to return in this operation.
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - name: x-amzn-principal
        in: header
        required: true
        description: The principal.
        schema:
          type: string
      summary: Amazon IoT Core List Principal Things
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      tags:
      - Principals
      security:
      - hmac: []
    servers:
    - url: http://iot.{region}.amazonaws.com
      variables:
        region:
          description: The AWS region
          enum:
          - us-east-1
          - us-east-2
          - us-west-1
          - us-west-2
          - us-gov-west-1
          - us-gov-east-1
          - ca-central-1
          - eu-north-1
          - eu-west-1
          - eu-west-2
          - eu-west-3
          - eu-central-1
          - eu-south-1
          - af-south-1
          - ap-northeast-1
          - ap-northeast-2
          - ap-northeast-3
          - ap-southeast-1
          - ap-southeast-2
          - ap-east-1
          - ap-south-1
          - sa-east-1
          - me-south-1
          default: us-east-1
      description: The AWS IoT multi-region endpoint
    - url: https://iot.{region}.amazonaws.com
      variables:
        region:
          description: The AWS region
          enum:
          - us-east-1
          - us-east-2
          - us-west-1
          - us-west-2
          - us-gov-west-1
          - us-gov-east-1
          - ca-central-1
          - eu-north-1
          - eu-west-1
          - eu-west-2
          - eu-west-3
          - eu-central-1
          - eu-south-1
          - af-south-1
          - ap-northeast-1
          - ap-northeast-2
          - ap-northeast-3
          - ap-southeast-1
          - ap-southeast-2
          - ap-east-1
          - ap-south-1
          - sa-east-1
          - me-south-1
          default: us-east-1
      description: The AWS IoT multi-region endpoint
    - url: http://iot.{region}.amazonaws.com.cn
      variables:
        region:
          description: The AWS region
          enum:
          - cn-north-1
          - cn-northwest-1
          default: cn-north-1
      description: The AWS IoT endpoint for China (Beijing) and China (Ningxia)
    - url: https://iot.{region}.amazonaws.com.cn
      variables:
        region:
          description: The AWS region
          enum:
          - cn-north-1
          - cn-northwest-1
          default: cn-north-1
      description: The AWS IoT endpoint for China (Beijing) and China (Ningxia)
  /things/{thingName}/principals:
    put:
      operationId: AttachThingPrincipal
      summary: Attach Thing Principal
      description: Attaches the specified principal to the specified thing. A principal can be X.509 certificates, Amazon Cognito identities or federated identities. Requires permission to access the AttachThingPrincipal action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachThingPrincipalResponse'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException_2'
        '400':
          description: InvalidRequestException; ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException_2'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException_2'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException_2'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException_2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachThingPrincipalRequest'
      tags:
      - Principals
      security:
      - sigv4: []
    delete:
      operationId: DetachThingPrincipal
      summary: Detach Thing Principal
      description: Detaches the specified principal from the specified thing. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. This call is asynchronous. It might take several seconds for the detachment to propagate. Requires permission to access the DetachThingPrincipal action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetachThingPrincipalResponse'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException_2'
        '400':
          description: InvalidRequestException; ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException_2'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException_2'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException_2'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException_2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetachThingPrincipalRequest'
      tags:
      - Principals
      security:
      - sigv4: []
    servers:
    - url: https://iot.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
  /principals/things:
    get:
      operationId: getPrincipalsThings
      summary: List Principal Things
      description: Lists the things associated with the specified principal. A principal can be X.509 certificates, IAM users, groups, and roles, Amazon Cognito identities or federated identities. Requires permission to access the ListPrincipalThings action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPrincipalThingsResponse_2'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException_2'
        '400':
          description: InvalidRequestException; ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException_2'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException_2'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException_2'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException_2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPrincipalThingsRequest'
      tags:
      - Principals
      security:
      - sigv4: []
      x-operation-id-source: normalized
      x-operation-id-original: ListPrincipalThings
    servers:
    - url: https://iot.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
  /principals/things-v2:
    get:
      operationId: ListPrincipalThingsV2
      summary: List Principal Things V2
      description: Lists the things associated with the specified principal. A principal can be an X.509 certificate or an Amazon Cognito ID. Requires permission to access the ListPrincipalThings action.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPrincipalThingsV2Response'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException_2'
        '400':
          description: InvalidRequestException; ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException_2'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException_2'
        '503':
          description: ServiceUnavailableException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableException_2'
        '401':
          description: UnauthorizedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedException_2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListPrincipalThingsV2Request'
      tags:
      - Principals
      security:
      - sigv4: []
    servers:
    - url: https://iot.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
components:
  schemas:
    ThingName:
      type: string
      pattern: '[a-zA-Z0-9:_-]+'
      minLength: 1
      maxLength: 128
    ThingNameList:
      type: array
      items:
        $ref: '#/components/schemas/ThingName'
    ServiceUnavailableException: {}
    ResourceNotFoundException: {}
    UnauthorizedException: {}
    InternalFailureException: {}
    NextToken:
      type: string
    ListPrincipalThingsResponse:
      type: object
      properties:
        things:
          allOf:
          - $ref: '#/components/schemas/ThingNameList'
          - description: The things.
        nextToken:
          allOf:
          - $ref: '#/components/schemas/NextToken'
          - description: The token to use to get the next set of results, or <b>null</b> if there are no additional results.
      description: The output from the ListPrincipalThings operation.
    ThrottlingException: {}
    InvalidRequestException: {}
    PrincipalThingObject:
      type: object
      properties:
        thingName:
          type: string
          description: The name of the thing.
        thingPrincipalType:
          type: string
          enum:
          - EXCLUSIVE_THING
          - NON_EXCLUSIVE_THING
          description: The type of the relation you want to specify when you attach a principal to a thing. The value defaults to NON_EXCLUSIVE_THING. EXCLUSIVE_THING - Attaches the specified principal to the specified thing, exclusively. The thing will be the only thing that’s attached to the principal. NON_EXCLUSIVE_THING - Attaches the specified principal to the specified thing. Multiple things can be attached to the principal.
      required:
      - thingName
    ServiceUnavailableException_2:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    AttachThingPrincipalResponse:
      type: object
      properties: {}
    UnauthorizedException_2:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    InternalFailureException_2:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    ListPrincipalThingsRequest:
      type: object
      properties:
        nextToken:
          type: string
          description: To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
        maxResults:
          type: integer
          description: The maximum number of results to return in this operation.
        principal:
          type: string
          description: The principal.
      required:
      - principal
    DetachThingPrincipalRequest:
      type: object
      properties:
        thingName:
          type: string
          description: The name of the thing.
        principal:
          type: string
          description: If the principal is a certificate, this value must be ARN of the certificate. If the principal is an Amazon Cognito identity, this value must be the ID of the Amazon Cognito identity.
      required:
      - thingName
      - principal
    ListPrincipalThingsResponse_2:
      type: object
      properties:
        things:
          type: array
          items:
            type: string
          description: The things.
        nextToken:
          type: string
          description: The token to use to get the next set of results, or null if there are no additional results.
    DetachThingPrincipalResponse:
      type: object
      properties: {}
    AttachThingPrincipalRequest:
      type: object
      properties:
        thingName:
          type: string
          description: The name of the thing.
        principal:
          type: string
          description: The principal, which can be a certificate ARN (as returned from the CreateCertificate operation) or an Amazon Cognito ID.
        thingPrincipalType:
          type: string
          enum:
          - EXCLUSIVE_THING
          - NON_EXCLUSIVE_THING
          description: The type of the relation you want to specify when you attach a principal to a thing. EXCLUSIVE_THING - Attaches the specified principal to the specified thing, exclusively. The thing will be the only thing that’s attached to the principal. NON_EXCLUSIVE_THING - Attaches the specified principal to the specified thing. Multiple things can be attached to the principal.
      required:
      - thingName
      - principal
    ListPrincipalThingsV2Request:
      type: object
      properties:
        nextToken:
          type: string
          description: To retrieve the next set of results, the nextToken value from a previous response; otherwise null to receive the first set of results.
        maxResults:
          type: integer
          description: The maximum number of results to return in this operation.
        principal:
          type: string
          description: The principal. A principal can be an X.509 certificate or an Amazon Cognito ID.
        thingPrincipalType:
          type: string
          enum:
          - EXCLUSIVE_THING
          - NON_EXCLUSIVE_THING
          description: The type of the relation you want to filter in the response. If no value is provided in this field, the response will list all things, including both the EXCLUSIVE_THING and NON_EXCLUSIVE_THING attachment types. EXCLUSIVE_THING - Attaches the specified principal to the specified thing, exclusively. The thing will be the only thing that’s attached to the principal. NON_EXCLUSIVE_THING - Attaches the specified principal to the specified thing. Multiple things can be attached to the principal.
      required:
      - principal
    ListPrincipalThingsV2Response:
      type: object
      properties:
        principalThingObjects:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalThingObject'
          description: A list of thingPrincipalObject that represents the principal and the type of relation it has with the thing.
        nextToken:
          type: string
          description: The token to use to get the next set of results, or null if there are no additional results.
    ResourceNotFoundException_2:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
    InvalidRequestException_2:
      type: object
      properties:
        message:
          type: string
          description: The message for the exception.
  parameters:
    X-Amz-SignedHeaders:
      name: X-Amz-SignedHeaders
      in: header
      schema:
        type: string
      required: false
    X-Amz-Security-Token:
      name: X-Amz-Security-Token
      in: header
      schema:
        type: string
      required: false
    X-Amz-Date:
      name: X-Amz-Date
      in: header
      schema:
        type: string
      required: false
    X-Amz-Signature:
      name: X-Amz-Signature
      in: header
      schema:
        type: string
      required: false
    X-Amz-Credential:
      name: X-Amz-Credential
      in: header
      schema:
        type: string
      required: false
    X-Amz-Content-Sha256:
      name: X-Amz-Content-Sha256
      in: header
      schema:
        type: string
      required: false
    X-Amz-Algorithm:
      name: X-Amz-Algorithm
      in: header
      schema:
        type: string
      required: false
  securitySchemes:
    hmac:
      type: apiKey
      name: Authorization
      in: header
      description: Amazon Signature authorization v4
      x-amazon-apigateway-authtype: awsSigv4
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: iot
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/iot/
x-refined-from:
- amazon-iot-core-openapi-original.yml
- amazon-iot-core-principals-api-openapi.yml
x-hasEquivalentPaths: true