Documentation

Mistake on this page? Email us

Access Device Management with API keys

Device Management exposes REST APIs that let you use the services from your application-server. To access an API, you first need to create an API key, which enables your web application to access the APIs.

You must create an API key separately for each application instance. The API key is used to bind the action to application's corresponding event notification channel. If some other application instance uses the same API key, it overwrites the channel and events are not received in the original channel.

Warning: Do not expose the API key to the outside world in any manner, for example in an application which is delivered to your customers.

Note: You can use the API key to access all the endpoints in Device Management and use a single API key for multiple concurrent requests. However, it must be application-specific in the web application side. This is important as the API key is used for binding data to applications. For example, when writing to a device with PUT /v2/endpoints/{device-id}/{resourcePath} command, the asynchronous response is delivered to the event notification channel created by the same API key. This means that each web-application with its own event notification channel must have its own API key.

Secure REST connectivity

Generating an API key

You can generate an API key through the portal or the APIs.

Using the portal

  1. Log in to Device Management Portal with the account's Admin user.

  2. Navigate to Access management > API keys.

  3. In top right corner, click NEW API KEY.

  4. Name the API key.

  5. Select the key group. Note that the key will have the same privileges as the group you select, meaning an administrator key will have full privileges.

  6. Click Create API key. A key is generated.

    Note: Once you leave the API key page, you will not be able to retrieve the full API key information as the last 32 characters are considered to be the secret part. If you did leave the page without storing the key, delete the key and create it again.

    The full API key is used for authorization only. Never put it into your request as a part of the URI or query parameters as it may be then visible in network server logs.

  • Store the generated API key in your system.

  • Using the APIs

    You can create a new API key using an HTTP request to the APIs. Note that you can only perform this action if you authenticate it with an administrator's API key. In other words, you must already have at least one administrator key before you can use the APIs to create any other keys.

    To create a new API key with an existing one, use the /v3/api-keys endpoint.

    Using your API key in an application

    Device Management supports bearer authentication of HTTP requests. Pass the API key in the Authorization header:

    Authorization: Bearer ak_272f4259b2b1470599c19bc4a473d3cb
    

    Request example:

    $ curl https://api.us-east-1.mbedcloud.com/v3/devices?limit=8 -H "Authorization: Bearer ak_272f4259b2b1470599c19bc4a473d3cb"
    

    Revoking keys

    If you think your key has been compromised, you can revoke it by either deleting it or resetting it. Both actions are available in the portal and APIs.