REST API for Oracle Internet of Things Cloud Service

Activate a Device

post

/iot/api/v2/activation/direct

Enables a device to directly activate itself

Request

Supported Media Types

application/json

Query Parameters

createDraft(optional): string

Entity description is undefined
requestCertificate(optional): boolean

Entity description is undefined

Root Schema : DirectActivationResponse_create

Type: object

Show Source

activationTime: integer

Time when the activation occurred
certificate: string

Property description was not set
endpointId: string

Endpoint identifier of the device that was activated
endpointState: string

Lifecycle state of the endpoint after activation

{
    "properties":{
        "activationTime":{
            "description":"Time when the activation occurred",
            "type":"integer"
        },
        "certificate":{
            "description":"Property description was not set",
            "type":"string"
        },
        "endpointId":{
            "description":"Endpoint identifier of the device that was activated",
            "type":"string"
        },
        "endpointState":{
            "description":"Lifecycle state of the endpoint after activation",
            "type":"string"
        }
    },
    "required":[
        "certificate",
        "endpointId",
        "activationTime",
        "endpointState"
    ],
    "type":"object"
}

Response

Supported Media Types

application/json
application/vnd.oracle.resource+json;type=singular

200 Response

Successfully processed.

Root Schema : DirectActivationResponse_receive

Type: object

Show Source

activationTime: integer

Time when the activation occurred
certificate: string

Property description was not set
endpointId: string

Endpoint identifier of the device that was activated
endpointState: string

Lifecycle state of the endpoint after activation

{
    "properties":{
        "activationTime":{
            "description":"Time when the activation occurred",
            "type":"integer"
        },
        "certificate":{
            "description":"Property description was not set",
            "type":"string"
        },
        "endpointId":{
            "description":"Endpoint identifier of the device that was activated",
            "type":"string"
        },
        "endpointState":{
            "description":"Lifecycle state of the endpoint after activation",
            "type":"string"
        }
    },
    "required":[
        "certificate",
        "endpointId",
        "activationTime",
        "endpointState"
    ],
    "type":"object"
}

400 Response

Bad Request. The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

401 Response

Unauthorized. The request requires user authentication.

403 Response

Forbidden. The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

406 Response

Request Not Acceptable. The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.

415 Response

Unsupported Media Type. The request entity has a media type which the server or resource does not support.

Examples

Request

The following explains how to activate a device with an example.

POST https://iotserver/iot/api/v2/activation/direct

Accept:application/json 
Content-Type:application/json'
Authorization:Bearer 63b73a734bbd02ed30f995651c15ed79
X-ActivationId: 6e5e3e593bcf-1c79{
   "deviceModels":[
      "urn:oracle:iot:dcd:capability:direct_activation",
      "urn:oracle:iot:dcd:capability:power_management_1455913944198"
   ],
   "certificationRequestInfo":{
      "subject":"6e5e3e593bcf-1c79",
      "subjectPublicKeyInfo":{
         "algorithm":"RSA",
         "publicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqKoAHAUj7Qh9cxwVQtMdxxPqhIJ8Q+MW\r\nCYEQBxe76WB26ypzqvEs8Uihl+2YUX2OxZsb74/5SwQisEduu+FXcwxUnI88Tq13Gehfwg/eSnyy\r\nWy8h8DI3Ktdozm9vktaQLrtG0Qq94vcL0I1s0jRJgAt2eIf7M/5EO0FdNipZ2B2/uDpzwktlSnAY\r\noNFODTOMl9NDleqJwSrRVt7oKlieLLF/WUuHbYlfmQ7NtWS48yRzuilA4SykD1YudzaG6LPxjuXq\r\n8YLUZnO3mf1Qrq60/PR7J1X7nnRajPXvkW1aWMC4zJ1f9I84iyL6Zr/eR3m2HDpyAtEQo5S+iFPt\r\nNwo/xwIDAQAB\r\n",
         "format":"X.509",
         "secretHashAlgorithm":"HmacSHA256"
      },
      "attributes":null
   },
   "signatureAlgorithm":"SHA256withRSA",
   "signature":"qA/AmRXQhUx592RqkXOMzuZtKrRm8NDo/PWt9dvolSA4fFfTy2Okt+5zivwXptKBoMyD98OFkJ19\r\n/Y2dyhZP7TuolvM0QGGcn5/29wVviK4DqWHZRkEyqvTsRQcQ85sFi8eEnXnQMIys6/5LttowWyM5\r\nRcZ/N2DPXnpPPPW4j6NcRoXj4JlMGq1e7xKV+n1sczXlkg4PtLYPxCCZ7rbsntSVI7xfhwru34Tm\r\n65nbCgSUtBJIsC6so7XLeRsqCO/RmdphNK9/NkbuCU7G2O9N+VqPb4cwXcPbVMa8QNIJFG3Kfn8B\r\nye0QfCh1ZMH69yJ58QCnF8PmTjWR88iCwEy2jA==\r\n"
}

Example of cURL command

The following example shows how to enable Device with Activation Id=6e5e3e593bcf-1c79 to directly activate itself by submitting a POST request on the REST resource using cURL.

Note that in both request and response, http://iotserver will be replaced by the name and port of your assigned Oracle IoT Cloud Service instance. The format of the Cloud Service instance is https://myinstance-myidentitydomain.iot.us.oraclecloud.com and the default port is 443.

First of all, we need to call the GET /iot/api/v2/activation/policy API to get the parameters needed to perform activation. For this example, we got the following response:

{     
	"keyType":"RSA",    
	"hashAlgorithm":"SHA256withRSA",    
	"keySize":2048 
}

The keyType field is added to the algorithm field in the direct activation request payload.

The hashAlgorithm field is added to the signatureAlgorithm field in the payload.

The subject is the device's Activation Id (6e5e3e593bcf-1c79) .

For direct activation, the device model must contain the urn:oracle:iot:dcd:capability:direct_activation device model.

The Authorization token is obtained by calling the Authentication API, where issuer is the device's Activation Id (6e5e3e593bcf-1c79) and scope=oracle/iot/activation.

The device's shared secret is "WFlBRkZ4NzhheXFvcA==".

The secretHashAlgorithm to hash the secret_hash is "HmacSHA256".

The secret_hash is HmacSHA256(6e5e3e593bcf-1c79, WFlBRkZ4NzhheXFvcA==).

The payload of the signature is, payload_string = "6e5e3e593bcf-1c79" + "\n" + "RSA" + "\n" + "X.509" + "\n" + "HmacSHA256";.

The signature is: SHA256withRSA("payload_string + secret_hash + public_key", device's private_key).

The above information is provided in activation.json file.

For more information about cURL, see Use cURL.

curl -X POST -H 'Accept:application/json' -H 'Content-Type: application/json' -H 'Authorization: Bearer afdc12c3259f8d2b45a11106de774bba' -H 'X-ActivationId: 6e5e3e593bcf-1c79' -d @activation.json https://iotserver/iot/api/v2/activation/direct

The format of the activation.json file should be as follows:

{
   deviceModels":[
      "urn:oracle:iot:dcd:capability:direct_activation",
      "urn:oracle:iot:dcd:capability:power_management_1455913944198"
   ],
   "certificationRequestInfo":{
      "subject":"6e5e3e593bcf-1c79",
      "subjectPublicKeyInfo":{
         "algorithm":"RSA",
         "publicKey":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqKoAHAUj7Qh9cxwVQtMdxxPqhIJ8Q+MW\r\nCYEQBxe76WB26ypzqvEs8Uihl+2YUX2OxZsb74/5SwQisEduu+FXcwxUnI88Tq13Gehfwg/eSnyy\r\nWy8h8DI3Ktdozm9vktaQLrtG0Qq94vcL0I1s0jRJgAt2eIf7M/5EO0FdNipZ2B2/uDpzwktlSnAY\r\noNFODTOMl9NDleqJwSrRVt7oKlieLLF/WUuHbYlfmQ7NtWS48yRzuilA4SykD1YudzaG6LPxjuXq\r\n8YLUZnO3mf1Qrq60/PR7J1X7nnRajPXvkW1aWMC4zJ1f9I84iyL6Zr/eR3m2HDpyAtEQo5S+iFPt\r\nNwo/xwIDAQAB\r\n",
         "format":"X.509",
         "secretHashAlgorithm":"HmacSHA256"
      },
      "attributes":{

      }
   },
   "signatureAlgorithm":"SHA256withRSA",
   "signature":"FRViLMfUU4AaHMSCxDki5OAscXZcdv4HFcJ+3TpQQyWnwf4/1sBa/vGvBktoFKC47HXhTZjk/m3Bi/mPZlh/4whazplaHUNtCiiMSvzbq9g4513uZut3DnSPV1XZDHmIQViP3VdzrFojNBJlVtVfvs72QIO/iKqx8+1dIF8YPL2F6rhMTJuOenIWE/2+t3NBJbkLGrjns1oqrTZqDRFRBVcr5vvld6vXrNap2zvwwkSzj6uFYgIAd2ARJ6maU060Kw64fz6LFKjIoVPxEAIMrBnMV0gq+KerNYX0N6w3h7qcI6qIiP66KWbT8ngVvdp88Wg187JaiVgs1sGS8COGqg=="
}

Example of Response Header

The following shows an example of the response header when the request is successful.

HTTP/1.1 200 OK 
Content-Type: application/json

Example of Response Body

The following example shows the contents of the response body containing the endpoint ID for the newly activated device in JSON format.

{
   "endpointId":"0-V4HQ",
   "activationTime":"2016-01-20T19:16:40Z",
   "endpointState":"ACTIVATED"
}