REST API for Oracle Internet of Things Cloud Service

Authenticate with Server and Get Access Token

post

/iot/api/v2/oauth2/token

This API implements the the OAuth2 client credentials grant flow, which enables clients to obtain an access token by authenticating themselves. The client credentials flow is used when the client itself owns the data and does not need delegated access from a resource owner, or when delegated access has been provided outside of the OAuth2 flow. This flow relies on the client to authenticate with the server, and the client's authentication credentials remain confidential.

This API supports the following authentication mechanisms:

client_assertion: used by the client that asserts its identity using a JSON Web Token (JWT). The JWT contains the signature that proves the possession of the private key.

The OAuth2 scope attribute is required for all requests for access tokens. The server supports the following scopes:

scope=oracle/iot/activation: used to obtain an access token for calling Activation REST APIs only
scope=empty scope, used to obtain an access token for calling all other REST APIs

Any other scope value results in a BAD_REQUEST error.

JSON Web Token (JWT)

An open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with HMAC algorithm) or a public/private key pair using RSA.

JSON Web Tokens consist of three parts separated by dots (.), which are:

Header
Payload
Signature

Therefore, a JWT typically looks like the following.

xxxxx.yyyyy.zzzzz

Header

The header for authentication consists of two parts: the type of the token, which is JWT, and the hashing algorithm such as HmacSHA256 ("HS256") or SHA256withRSA ("RS256").

Payload

The second part of the token is the payload, which contains the claims about the Device Endpoint.

Required claims: These are a set of required claims for authentication:

iss (issuer, should be the Device Activation ID for Activation purpose and Device Endpoint Id for Messaging purpose)
exp (expiration time, the epoch value in seconds. If the expiration time is outside a 30 minute window, the request is rejected)
aud (audience, should be "oracle/iot/oauth2/token").

Signature

To create the signature part you have to take the encoded header, the encoded payload, a key, the algorithm specified in the header, and sign that in the following way:

Algorithm(base64UrlEncode(header) + "." +base64UrlEncode(payload), key)

Note HmacSHA256 is only used in the activation procedure (scope=oracle/iot/activation), and the key used for the signature is the shared secret of the Device Endpoint. SHA256withRSA is used in other procedures (scope is empty), such as posting a message, and the secret key of the Device Endpoint is used as the key for signature.

Request

Supported Media Types

application/x-www-form-urlencoded

Form Parameters

client_assertion(optional): string

The client assertion data as a JWT token.
client_assertion_type(optional): string

The client assertion type. The value MUST be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
grant_type: string

The grant type. For the client credentials flow, the value MUST be client_credentials.
scope(optional): string

The scope of the access token request. The value MUST be empty or oracle/iot/activation.

Response

Supported Media Types

application/json

200 Response

Root Schema : OAuth2TokenResponse

Type: object

OAuth2 token object sent as a response to the token request

Show Source

access_token: string

The access token (for example, 8vsdettdjjjdc-aggdgsgcbbsgd)
expires_in(optional): integer(int64)

Time in miliseconds for the access token to expire (for example, 3600000)
token_type(optional): string

The type of the access token issued (for example, Bearer). This value MUST be specified in the Authorization header in the HTTP request.

{
    "type":"object",
    "description":"OAuth2 token object sent as a response to the token request",
    "required":[
        "access_token"
    ],
    "properties":{
        "access_token":{
            "type":"string",
            "description":"The access token (for example, 8vsdettdjjjdc-aggdgsgcbbsgd)"
        },
        "expires_in":{
            "type":"integer",
            "format":"int64",
            "description":"Time in miliseconds for the access token to expire (for example, 3600000)"
        },
        "token_type":{
            "type":"string",
            "description":"The type of the access token issued (for example, Bearer). This value MUST be specified in the Authorization header in the HTTP request."
        }
    }
}

400 Response

Bad Request. This error is returned if the authentication information provided is not valid.

401 Response

Unauthorized. This error is returned if the access token is not valid or has expired.

403 Response

Forbidden. This error is returned if the operation is not allowed for the request.

Examples

The following shows you two examples, one on how to get an activation token and another on how to get a message token from the IoT Cloud Service instance.

Get Activation Token

The following shows an example of a request header:

Content-Type: application/x-www-form-urlencoded
Accept: application/json

Example of Request Form Parameters

The following shows an example of form parameters:

grant_type=client_credentials
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwLVlRRlEiLCJleHAiOjE0Njc3NjYyNjMsImF1ZCI6Im9yYWNsZS9pb3Qvb2F1dGgyL3Rva2VuIn0.AU9eYChN9EOupzyLoWf0AMZ0QiK4dnmpA1n5tb_kSSw
scope=oracle/iot/activation

Example of cURL Command

The following example shows how to use cURL to send a client assertion to get an access token for performing activation operations on Device with Activation ID=6e5e3e593bcf-1c79. The activation secret of the device is secret, and the state is REGISTERED. The JWT token for client_assertion contains the following information:

Header: {
  "typ": "JWT", 
  "alg": "HS256"
}
Payload: { 
 "iss": "6e5e3e593bcf-1c79", 
 "exp": 1467751899, 
 "aud": "oracle/iot/oauth2/token"
}

The signature is obtained from signing the "Header.Payload" by the HmacSHA256 algorithm using "secret" as the key. This algorithm is typically used during device activation.

The JSON Web Token Builder site might help you construct a valid JWT token.

Note that in the request, http://iotserver will be replaced by the name and port of your assigned 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.

For more information about cURL, see Use cURL.

curl -X POST -H 'Accept:application/json' -H 'Content-Type: application/x-www-form-urlencoded' --data "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIwLVlRRlEiLCJleHAiOjE0Njc3NjYyNjMsImF1ZCI6Im9yYWNsZS9pb3Qvb2F1dGgyL3Rva2VuIn0.AU9eYChN9EOupzyLoWf0AMZ0QiK4dnmpA1n5tb_kSSw&scope=oracle/iot/activation" http://iotserver/iot/api/v2/oauth2/token

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 expiration time, token type, and token value in JSON format.

{
   "expires_in":3600000,
   "token_type":"Bearer",
   "access_token":"677b4afa55236110825ae0a3d38275ad"
}

Get Message Token

The following shows an example of a request header:

Content-Type: application/x-www-form-urlencoded
Accept: application/json

Example of Request Form Parameters

grant_type=client_credentials
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBQUFBQUFRMEZSMEEtQ0UiLCJhdWQiOiJvcmFjbGUvaW90L29hdXRoMi90b2tlbiIsImV4cCI6MTQ2OTQ3NDE5M30.oDiGi13Xw1ZJJ3iMDOSpZLN1NNfTVF8wJuWy2sMzcKKVIUbULeFCUoyd8SZiJBXMQDd4n_dRtF5vq7or3kGGiKOiWkS3V-r1qqqL0-o02Hh2tQ4AOHvwMRbEQOGE3lA7doNRd9sr7BR5zQGu4yahCh5581Q_4B5gV-ZN65gbdt4
scope=

Example of cURL Command

The following example shows how to use cURL to send a client assertion to get an access token for performing activation operations on Device with Endpoint ID=0-AECA. The device is already ACTIVATED. The JWT token for client_assertion contains the following information:

Header: {"typ": "JWT", "alg": "RS256"}
Payload: { "iss": "0-AECA", "exp": 1469474193, "aud": "oracle/iot/oauth2/token"}

The device has the following private key, obtained in the activation process:

MIICWwIBAAKBgQDdlatRjRjogo3WojgGHFHYLugdUWAY9iR3fy4arWNA1KoS8kVw33cJibXr8bvwUAUparCwlvdbH6dvEOfou0/gCFQsHUfQrSDv+MuSUMAe8jzKE4qW+jK+xQU9a03GUnKHkkle+Q0pX/g6jXZ7r1/xAK5Do2kQ+X5xK9cipRgEKwIDAQABAoGAD+onAtVye4ic7VR7V50DF9bOnwRwNXrARcDhq9LWNRrRGElESYYTQ6EbatXS3MCyjjX2eMhu/aF5YhXBwkppwxg+EOmXeh+MzL7Zh284OuPbkglAaGhV9bb6/5CpuGb1esyPbYW+Ty2PC0GSZfIXkXs76jXAu9TOBvD0ybc2YlkCQQDywg2R/7t3Q2OE2+yo382CLJdrlSLVROWKwb4tb2PjhY4XAwV8d1vy0RenxTB+K5Mu57uVSTHtrMK0GAtFr833AkEA6avx20OHo61Yela/4k5kQDtjEf1N0LfI+BcWZtxsS3jDM3i1Hp0KSu5rsCPb8acJo5RO26gGVrfAsDcIXKC+bQJAZZ2XIpsitLyPpuiMOvBbzPavd4gY6Z8KWrfYzJoI/Q9FuBo6rKwl4BFoToD7WIUS+hpkagwWiz+6zLoX1dbOZwJACmH5fSSjAkLRi54PKJ8TFUeOP15h9sQzydI8zJU+upvDEKZsZc/UhT/SySDOxQ4G/523Y0sz/OZtSWcol/UMgQJALesy++GdvoIDLfJX5GBQpuFgFenRiRDabxrE9MNUZ2aPFaFp+DyAe+b4nDwuJaW2LURbr8AEZga7oQj0uYxcYw==

The signature is obtained by signing the "Header.Payload" by the SHA256withRSA algorithm using the device's private key. This algorithm is typically used for getting a message token.

The JSON Web Token Builder site might help you construct a valid JWT token.

For more information about cURL, see Use cURL.

curl -X POST -H 'Accept:application/json' -H 'Content-Type: application/x-www-form-urlencoded' --data "grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJBQUFBQUFRMEZSMEEtQ0UiLCJhdWQiOiJvcmFjbGUvaW90L29hdXRoMi90b2tlbiIsImV4cCI6MTQ2OTQ3NDE5M30.oDiGi13Xw1ZJJ3iMDOSpZLN1NNfTVF8wJuWy2sMzcKKVIUbULeFCUoyd8SZiJBXMQDd4n_dRtF5vq7or3kGGiKOiWkS3V-r1qqqL0-o02Hh2tQ4AOHvwMRbEQOGE3lA7doNRd9sr7BR5zQGu4yahCh5581Q_4B5gV-ZN65gbdt4&scope=" http://iotserver/iot/api/v2/oauth2/token

Example of Response Header

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

status: 200 OK 
Content-Type: application/json

Example of Response Body

The following example shows the contents of the response body containing the expiration time, token type, and token value in JSON format.

{
   "expires_in":3600000,
   "token_type":"Bearer",
   "access_token":"6074b571c671fe3cd548a8e668042187"
}