Cumulocity Device Credentials API

openapi: 3.2.0
info:
  version: Latest
  title: Cumulocity Device credentials API
  x-logo:
    url: https://www.cumulocity.com/docs/images/logo-platform.svg
    backgroundColor: '#F8F8F8'
    altText: Cumulocity
    href: https://www.cumulocity.com/api
  description: '# REST implementation


    This section describes the aspects common to all REST-based interfaces of Cumulocity. The interfaces are based on the Hypertext Transfer Protocol 1.1 using HTTPS. ## HTTP usage


    ### Application management


    Cumulocity uses a so-called "application key" to distinguish requests coming from devices and traffic from applications. If you write an application, pass the following header as part of all requests:


    ```markup

    X-Cumulocity-Application-Key:

    ```


    For example, if you registered your application in the Cumulocity Administration application with the key "myapp", your requests should contain the header:


    ```markup

    X-Cumulocity-Application-Key: myapp

    ```


    This makes your application subscribable and billable. If you implement a device, do not pass the key. > **ⓘ Info:** Make sure that you pass the key in **all** requests coming from an application. If you leave out the key,

    > the request will be considered as a device request, and the corresponding device will be marked as "available". ### Limited HTTP clients


    If you use an HTTP client that can only perform GET and POST methods in HTTP, you can emulate the other methods through an additional "X-HTTP-METHOD" header. Simply issue a POST request and add the header, specifying the actual REST method to be executed. For example, to emulate the "PUT" (modify) method, you can use:


    ```http

    POST ... X-HTTP-METHOD: PUT

    ```


    ### Processing mode


    Every update request (PUT, POST, DELETE) executes with a so-called *processing mode*. The processing modes are as follows:


    |Processing mode|Description|

    |---|---|

    |PERSISTENT (default)|Stores data in the Cumulocity database and sends data to the Streaming Analytics engine. Afterwards, Cumulocity returns the result of the request. This is the default mode.|

    |TRANSIENT|Sends data to the Streaming Analytics engine and immediately returns the results asynchronously but does not store data in Cumulocity’s database. This mode saves storage and processing costs and is useful for example when tracking devices in real time without requiring data to be stored.|

    |QUIESCENT|Behaves similar to the persistent mode with the exception that no real-time notifications will be sent.|

    |CEP|Behaves like the transient mode with the exception that no real-time notifications are sent.|


    To explicitly control the processing mode of an update request, you can use the "X-Cumulocity-Processing-Mode" header with a value of either "PERSISTENT", "TRANSIENT", "QUIESCENT" or "CEP":


    ```markup

    X-Cumulocity-Processing-Mode: PERSISTENT

    ```


    > **ⓘ Info:** Events are always delivered to CEP/Apama for all processing modes. This is independent from real-time notifications. ### Authorization


    All requests issued to Cumulocity are subject to authorization. To determine the required permissions, see the "Required role" entries for the individual requests. To learn more about the different permissions and the concept of ownership in Cumulocity, see Getting started > Technical concepts > Security aspects > Access control > Managing roles and assigning permissions in the Cumulocity user documentation. > **⚠️ Important:** In the Cumulocity API, each granular permission is identified by a unique “permission” string, which is prefixed with ROLE_ (for example, ROLE_ALARM_READ, ROLE_INVENTORY_ADMIN). Therefore, permissions are frequently referred to as “roles” throughout the API as well as in the configuration files. For example, the microservice manifest includes a requiredRoles field, which actually expects a permission string. See also the Glossary of the Cumulocity user documentation for the usage of the terms “permission” and “role” in the Cumulocity context. ### Media types


    Each type of data is associated with an own media type. The general format of media types is:


    ```markup

    application/vnd.com.nsn.cumulocity.+json;ver=;charset=UTF-8

    ```


    Each media type contains a parameter `ver` indicating the version of the type.'
servers:
- description: Cumulocity tenant
  url: https://<TENANT_DOMAIN>
security:
- Basic: []
- OAI-Secure: []
- SSO: []
- JWT-IAM: []
tags:
- name: Device credentials
  description: 'API methods to create device credentials in Cumulocity.


    Device credentials can be enquired by devices that do not have credentials for accessing a tenant yet.

    Since the device does not have credentials yet, a set of fixed credentials is used for this API.

    The credentials can be obtained by contacting support.


    > **⚠️ Important:** Do not use your tenant credentials with this API.


    > **ⓘ Info:** The Accept header should be provided in all POST requests, otherwise an empty response body will be returned.

    > **ⓘ Info:** Device credential passwords must comply with all the requirements listed here.'
paths:
  /devicecontrol/deviceCredentials:
    post:
      operationId: postDeviceCredentialsCollectionResource
      x-codegen-resource-name: createDeviceCredentials
      parameters:
      - $ref: '#/components/parameters/acceptHeader'
      - $ref: '#/components/parameters/processingModeHeader'
      tags:
      - Device credentials
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      - JWT-IAM: []
      summary: Create device credentials
      description: 'Create device credentials.


        Required roles


        ROLE_DEVICE_BOOTSTRAP'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request POST "https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials" \

          --header "Authorization: Basic <AUTHORIZATION>" \

          --header "Accept: application/json" \

          --header "Content-Type: application/json"

          --data-raw ''<Payload>'',

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials");

          client.Timeout = -1;


          var request = new RestRequest(Method.POST);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");

          request.AddHeader("Content-Type", "application/json");

          request.AddHeader("Accept", "application/json");

          request.AddParameter("application/json", "<Payload>", ParameterType.RequestBody);


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.post(\"https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\")\n    .header(\"Content-Type\", \"application/json\")\n    .header(\"Accept\", \"application/json\")\n    .body(\"<Payload>\")\n    .asString();\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"POST\", \"https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\",\n        \"Accept\": \"application/json\",\n        \"Content-Type\": \"application/json\"\n    })\n    .send(JSON.stringify( <Payload> ))\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\nimport json\n\nurl = \"https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\",\n  \"Accept\": \"application/json\",\n  \"Content-Type\": \"application/json\"\n}\nresponse = requests.request(\"POST\", url, headers = headers, data = json.dumps(<Payload>))\nprint(response.text.encode(\"utf8\"))\n"
      requestBody:
        required: true
        content:
          application/vnd.com.nsn.cumulocity.devicecredentials+json:
            examples:
              default:
                value:
                  id: '129129'
              with_security_token:
                value:
                  id: '129129'
                  securityToken: SecureDeviceToken
            schema:
              allOf:
              - $ref: '#/components/schemas/deviceCredentials'
              - required:
                - id
      responses:
        '200':
          description: Device credentials were created.
          content:
            application/vnd.com.nsn.cumulocity.devicecredentials+json:
              schema:
                $ref: '#/components/schemas/deviceCredentials'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
  /devicecontrol/bulkNewDeviceRequests:
    post:
      operationId: postBulkNewDeviceRequestCollectionResource
      x-codegen-resource-name: createBulkDeviceCredentials
      parameters:
      - $ref: '#/components/parameters/acceptHeader'
      - $ref: '#/components/parameters/processingModeHeader'
      tags:
      - Device credentials
      security:
      - Basic: []
      - OAI-Secure: []
      - SSO: []
      - JWT-IAM: []
      summary: Create a bulk device credentials request
      description: 'Create a bulk device credentials request. Device credentials and basic device representation can be provided within a CSV file which must be UTF-8 or ANSI encoded. The CSV file must have two sections. The first section is the first line of the CSV file. This line contains column names (headers):


        |Name|Mandatory|Description|

        |--- |--- |--- |

        |ID|Yes|The external ID of a device.|

        |CREDENTIALS|Yes*|Password for the device''s user. Mandatory, unless AUTH_TYPE is "CERTIFICATES", then CREDENTIALS can be skipped.|

        |AUTH_TYPE|No|Required authentication type for the device''s user. If the device uses credentials, this can be skipped or filled with "BASIC". Devices that use certificates must set "CERTIFICATES".|

        |TENANT|No|The ID of the tenant for which the registration is executed (only allowed for the management tenant).|

        |TYPE|No|The type of the device representation.|

        |NAME|No|The name of the device representation.|

        |ICCID|No|The ICCID of the device (SIM card number). If the ICCID appears in file, the import adds a fragment `c8y_Mobile.iccid`. The ICCID value is not mandatory for each row, see the example for an HTTP request below.|

        |IDTYPE|No|The type of the external ID. If IDTYPE doesn''t appear in the file, the default value is used. The default value is `c8y_Serial`. The IDTYPE value is not mandatory for each row, see the example for an HTTP request below.|

        |PATH|No|The path in the groups hierarchy where the device is added. PATH contains the name of each group separated by `/`, that is: `main_group/sub_group/.../last_sub_group`. If a group does not exist, the import creates the group.|

        |SHELL|No|If this column contains a value of 1, the import adds the SHELL feature to the device (specifically the `c8y_SupportedOperations` fragment). The SHELL value is not mandatory for each row, see the example for an HTTP request below.|

        |ENROLLMENT_OTP|No|If value for this column is present, then this is treated as device''s one time password(OTP) during device enrollment for certificate provisioning. AUTH_TYPE should be "CERTIFICATES" and "CREDENTIALS" will be skipped if present.|


        Section two is the rest of the CSV file. Section two contains the device information. The order and quantity of the values must be the same as of the headers. A separator is automatically obtained from the CSV file. Valid separator values are: `\t` (tabulation mark), `;` (semicolon) and `,` (comma). > **⚠️ Important:** The CSV file needs the "com_cumulocity_model_Agent.active" header with a value of "true" to be added to the request. > **ⓘ Info:** A bulk registration creates an elementary representation of the device. Then, the device needs to update it to a full representation with its own status. The device is ready to use only after it is updated to the full representation. Also see Device management > Device management application > Registering devices > Single device registration > Security token policy and Device management > Device integration > Device integration using REST > Integration life cycle. > **ⓘ Info:** A bulk registration for certificate provisioning creates temporary credentials for devices to authenticate


        A CSV file can appear in many forms (with regard to the optional tenant column and the occurrence of device information):


        * If a user is logged in as the management tenant, then the columns ID, CREDENTIALS and TENANT are mandatory, and the device credentials will be created for the tenant mentioned in the TENANT column. * If a user is logged in as a different tenant, for example, as `sample_tenant`, then the columns ID and CREDENTIALS are mandatory (if the file contains the TENANT column, it is ignored and the device credentials will be created for the tenant that is logged in). * If a user wants to add information about the device, the columns TYPE and NAME must appear in the CSV file. * If a user wants to add information about a SIM card number, the columns TYPE, NAME and ICCID must appear in the CSV file.'
      x-code-samples:
      - lang: cURL
        source: 'curl --location --request POST "https://<TENANT_DOMAIN>/devicecontrol/bulkNewDeviceRequests" \

          --header "Authorization: Basic <AUTHORIZATION>" \

          --header "Accept: application/json" \

          --form "file=@bulk_credential_request.csv"

          '
      - lang: C#
        source: 'var client = new RestClient("https://<TENANT_DOMAIN>/devicecontrol/bulkNewDeviceRequests");

          client.Timeout = -1;


          var request = new RestRequest(Method.POST);

          request.AddHeader("Authorization", "Basic <AUTHORIZATION>");

          request.AddHeader("Accept", "application/json");

          request.AddFile("file", "bulk_credential_request.csv");


          IRestResponse response = client.Execute(request);

          Console.WriteLine(response.Content);

          '
      - lang: Java
        source: "Unirest.setTimeouts(0, 0);\nHttpResponse<String> response = Unirest.post(\"https://<TENANT_DOMAIN>/devicecontrol/bulkNewDeviceRequests\")\n    .header(\"Authorization\", \"Basic <AUTHORIZATION>\")\n    .header(\"Accept\", \"application/json\")\n    .field(\"file\", new File(\"bulk_credential_request.csv\"))\n    .asString();\n"
      - lang: Node.js
        source: "var unirest = require(\"unirest\");\nvar req = unirest(\"POST\", \"https://<TENANT_DOMAIN>/devicecontrol/bulkNewDeviceRequests\")\n    .headers({\n        \"Authorization\": \"Basic <AUTHORIZATION>\",\n        \"Accept\": \"application/json\"\n    })\n    .attach(\"file\", \"bulk_credential_request.csv\")\n    .end(function (res) {\n        if (res.error) throw new Error(res.error);\n        console.log(res.raw_body);\n    });\n"
      - lang: Python
        source: "import requests\nimport json\n\nurl = \"https://<TENANT_DOMAIN>/devicecontrol/bulkNewDeviceRequests\"\nheaders = {\n  \"Authorization\": \"Basic <AUTHORIZATION>\",\n  \"Accept\": \"application/json\"\n}\nfiles = [(\"file\", open(\"bulk_credential_request.csv\", \"rb\"))]\n\nresponse = requests.request(\"POST\", url, headers = headers, files = files)\nprint(response.text.encode(\"utf8\"))\n"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  description: The CSV file to be uploaded.
                  type: string
                  format: binary
            encoding:
              file:
                contentType: text/csv
      responses:
        '201':
          description: A bulk of new device requests was created.
          content:
            application/vnd.com.nsn.cumulocity.bulknewdevicerequest+json:
              schema:
                $ref: '#/components/schemas/bulkNewDeviceRequest'
        '401':
          $ref: '#/components/responses/unauthorizedError'
        '403':
          $ref: '#/components/responses/operationNotAuthorized'
components:
  parameters:
    acceptHeader:
      name: Accept
      in: header
      description: Advertises which content types, expressed as MIME types, the client is able to understand.
      required: false
      schema:
        type: string
        minLength: 1
        example: application/json
    processingModeHeader:
      name: X-Cumulocity-Processing-Mode
      in: header
      description: Used to explicitly control the processing mode of the request. See [Processing mode](#processing-mode) for more details.
      required: false
      schema:
        type: string
        default: PERSISTENT
        enum:
        - PERSISTENT
        - TRANSIENT
        - QUIESCENT
        - CEP
        example: PERSISTENT
  responses:
    operationNotAuthorized:
      description: Not authorized to perform this operation.
    unauthorizedError:
      description: Authentication information is missing or invalid.
      content:
        application/vnd.com.nsn.cumulocity.error+json:
          schema:
            $ref: '#/components/schemas/error'
          example:
            error: security/Unauthorized
            message: 'Invalid credentials! : Bad credentials'
            info: https://www.cumulocity.com/guides/reference-guide/#error_reporting
  schemas:
    bulkNewDeviceRequest:
      type: object
      properties:
        numberOfAll:
          description: Number of lines processed from the CSV file, without the first line (column headers).
          type: integer
          example: 5
        numberOfCreated:
          description: Number of created device credentials.
          type: integer
          example: 3
        numberOfFailed:
          description: Number of failed creations of device credentials.
          type: integer
          example: 1
        numberOfSuccessful:
          description: Number of successful creations of device credentials. This counts both create and update operations.
          type: integer
          example: 4
        credentialUpdatedList:
          description: An array with the updated device credentials.
          type: array
          items:
            type: object
            properties:
              bulkNewDeviceStatus:
                description: The device credentials creation status.
                type: string
                title: NewDeviceStatus
                enum:
                - CREATED
                - FAILED
                - CREDENTIAL_UPDATED
                example: CREDENTIAL_UPDATED
              deviceId:
                description: Unique identifier of the device.
                type: string
                example: id04
        failedCreationList:
          description: An array with details of the failed device credentials.
          type: array
          items:
            type: object
            properties:
              bulkNewDeviceStatus:
                description: The device credentials creation status.
                type: string
                title: NewDeviceStatus
                enum:
                - CREATED
                - FAILED
                - CREDENTIAL_UPDATED
                example: FAILED
              deviceId:
                description: Unique identifier of the device.
                type: string
                example: id5
              failureReason:
                description: Reason for the failure.
                type: string
                example: Could not update the device
              line:
                description: Line where the failure occurred.
                type: string
                example: DeviceInfo{id='id5', credentials='credentials3', tenant='t00000003'}
    desc_self:
      title: SelfURL
      description: A URL linking to this resource.
      type: string
      format: uri
      readOnly: true
    error:
      type: object
      properties:
        error:
          description: The type of error returned.
          type: string
        message:
          description: A human-readable message providing more details about the error.
          type: string
        info:
          description: A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that identifies the error code reported.
          type: string
    deviceCredentials:
      type: object
      properties:
        id:
          description: The external ID of the device.
          type: string
        password:
          description: Password of these device credentials.
          type: string
          format: password
          readOnly: true
        self:
          $ref: '#/components/schemas/desc_self'
        tenantId:
          description: Tenant ID for these device credentials.
          type: string
          readOnly: true
        username:
          description: Username of these device credentials.
          type: string
          readOnly: true
        securityToken:
          writeOnly: true
          type: string
          description: 'Security token which is required and verified against during device request acceptance.

            See [Security token policy](https://www.cumulocity.com/docs/device-management-application/registering-devices/#security-token-policy) for more details on configuration.

            See [Update specific new device request status](#operation/putNewDeviceRequestResource) for details on submitting token upon device acceptance.

            '
      example:
        id: '129129'
        self: https://<TENANT_DOMAIN>/devicecontrol/deviceCredentials/129129
        tenantId: t07007007
        username: device_129129
        password: 5ecur3_p455w0rd
  securitySchemes:
    Basic:
      type: http
      scheme: basic
      description: 'The authorization header is formed as `Basic <Base64(<tenantID>/<c8yuser>:<password>)>`. For instance, if your tenantID, username and password are **t0071234**, **testuser** and **secret123** respectively, you can generate the Base64 string with the following command:


        ```shell

        $ echo -n t0071234/testuser:secret123 | base64

        ```


        and your authorization header would look like this:


        ```

        "Authorization": "Basic dDAwNzEyMzQvdGVzdHVzZXI6c2VjcmV0MTIz"

        ```

        '
    OAI-Secure:
      type: http
      scheme: bearer
      description: 'This is the recommended authorization method because it provides high security using authorization tokens to prove the identity of the user, and it is the default login mode on creating new tenants. This mode is an enhancement of the previous OAuth Internal authentication (available prior to 10.13.0).


        For more details about OAI-Secure authentication, see [Platform administration > Authentication > Basic settings > Login settings](https://www.cumulocity.com/docs/authentication/basic-settings/#login-settings) in the Cumulocity user documentation.

        '
    SSO:
      type: oauth2
      description: "The login with SSO requires a correct configuration on the [Cumulocity side](https://www.cumulocity.com/docs/authentication/sso/). With the configuration, an additional button is available on the Login page. After clicking the button, the user is redirected to authenticate with the configured authorization server. On successful login, the user is redirected to Cumulocity.\n\nAuthentication details are exchanged using cookies. There are two parts to it, the first is the authentication cookie that is handled automatically by the Cumulocity platform. The second is the XSRF-TOKEN cookie. When a client receives the cookie, it should take the value and put it in the X-XSRF-TOKEN request header in all subsequent requests.\n\nThe flow of authenticating with authentication code grant is as follows:\n\n![Authentication flow](images/oauth-simple-flow.png)\n\nThe first request executed by the browser is:\n\n```http\nGET /tenant/loginOptions\nHost: https://<TENANT_DOMAIN>\nAccept: application/vnd.com.nsn.cumulocity.loginoptioncollection+json\n```\n\nResponse sample:\n\n```json\n{\n    \"loginOptions\": [\n        {\n            \"buttonName\": \"Login with oauth\",\n            \"grantType\": \"<AUTHORIZATION_CODE>\",\n            \"initRequest\": \"https://<TENANT_DOMAIN>/tenant/oauth?response_type=code&tenant_id=<TENANT_ID>\",\n            \"self\": \"https://<TENANT_DOMAIN>/tenant/loginOptions/oauth2\",\n            \"type\": \"oauth2\"\n        },\n        ...\n    ],\n    \"self\": \"http://<TENANT_DOMAIN>/tenant/loginOptions/\"\n}\n```\n\nThe browser must invoke the request provided in the initRequest parameter.\n\nThe initRequest initiates the redirect, in which the user is prompted for credentials. After successful login, the user is redirected back to the browser, where it must capture the code request parameter. Then the request to exchange the code for the token is as follows:\n\n```http\nPOST /tenant/oauth?grant_type=authorization_code&code=<CODE>\nHost: https://<TENANT_DOMAIN>\n```\n\nA successful response will have no body but the following response headers:\n\n```\nSet-Cookie: authorization=<TOKEN>;\nSet-Cookie: XSRF-TOKEN=<XSRF-TOKEN>;\n```\n\nThe authorization cookie is valid for two weeks.\n"
      flows:
        clientCredentials:
          tokenUrl: /tenant/oauth?grant_type=authorization_code&code=<CODE>
          scopes: {}
    JWT-IAM:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'This kind of authentication substitutes the JWT authentication with OAuth2 access tokens from your Identity and Access Management (IAM).

        You can enable this in the [SSO configuration](https://www.cumulocity.com/docs/authentication/sso/).


        The HTTP header must include:


        ```

        "Authorization": "Bearer <Access token>"

        ```


        When a request with a bearer token in the header is received, Cumulocity checks if the access token is from your IAM (that is, if authentication is enabled in your SSO configuration), and verifies the authenticity of

        the token remotely against the IAM.

        '
x-tagGroups:
- name: Platform
  tags:
  - Platform API
- name: Alarms
  tags:
  - Alarm API
  - Alarm notification API
  - Alarms
- name: Applications
  tags:
  - Application API
  - Applications
  - Application versions
  - Application binaries
  - Bootstrap user
  - Current application
- name: Audits
  tags:
  - Audit API
  - Audits
- name: Device control
  tags:
  - Device control API
  - Device control notification API
  - Operations
  - Bulk operations
  - Device credentials
  - New device requests
  - Device control via SMS
- name: Events
  tags:
  - Event API
  - Event notification API
  - Events
  - Attachments
- name: Feature toggles
  tags:
  - Feature toggles API
- name: Identity
  tags:
  - Identity API
  - External IDs
- name: Inventory
  tags:
  - Inventory API
  - Inventory notification API
  - Managed objects
  - Binaries
  - Child operations
  - Query language
- name: Measurements
  tags:
  - Measurement API
  - Measurement notification API
  - Measurements
  - Measurements specifics
- name: Notifications 2.0
  tags:
  - About notifications 2.0
  - Notification 2.0 API
  - Subscriptions
  - Tokens
- name: Real-time notifications
  tags:
  - Real-time notification API
- name: Retentions
  tags:
  - Retention rules
- name: Tenants
  tags:
  - Tenant API
  - Tenants
  - Tenant applications
  - Trusted certificates
  - Device statistics
  - Usage statistics
  - Options
  - Login options
  - Login tokens
  - System options
- name: Users
  tags:
  - User API
  - Current User
  - Users
  - Groups
  - Roles
  - Inventory Roles
  - Device Permissions
- name: Certificate
  tags:
  - Certificate authority
  - Device enrollment
x-provenance:
  method: harvested
  publisher: Cumulocity
  source: https://cumulocity.com/api/core/dist/c8y-oas.yml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)