Keys API

This API allows managing master, device, collection, and distribution keys to access all resources or just a device or stream.

When a new account is created it will be assigned a default Master API Key. This key cannot be deleted nor updated, it's only possible to regenerate its token.

Authentication

All methods described in this page require that a master API key is specified in the X-M2X-KEY header. Any attempt of using a device level API key would result in a 403 Forbidden response. Learn more about API Keys.

List Keys

GET /keys

Retrieve list of keys associated with the specified account. This method accepts two optional parameter:

  • device: a Device ID; it will list all the keys that are associated with that specific device or its streams.
  • distribution: a Distribution ID; it will list all the keys that are associated with that specific distribution.
  • collection: a Collection ID; it will list all the keys that are associated with that collection.
  • if none is specified, it will only list the master API keys.

Responses

Success

Listing Master Keys

200 OK
Content-Type: application/json

{
  "keys": [
    {
      "name": "Master Key",
      "key": "a58c276d47d5a3eb34343cd2e6aebaf2",
      "master": true,
      "expires_at": null,
      "expired": false,
      "origin": null,
      "device_access": "public",
      "permissions": [
        "DELETE",
        "GET",
        "POST",
        "PUT"
      ]
    },
    {
      "name": "Primary Key",
      "key": "e829bd941c0b8b0381b93e98c3d971b5",
      "master": true,
      "expires_at": null,
      "expired": false,
      "origin": null,
      "device_access": "public",
      "permissions": [
        "DELETE",
        "GET",
        "POST",
        "PUT"
      ]
    }
  ]
}

Listing Device Keys

200 OK
Content-Type: application/json

{
  "keys": [
    {
      "name": "Primary Key",
      "key": "0b68f6e568ad37c16b92984cd961eae8",
      "master": false,
      "device": "https://api-m2x.att.com/v2/devices/2373c20eabce35c7292f51cd99e7a87b",
      "stream": null,
      "expires_at": null,
      "expired": false,
      "origin": null,
      "device_access": "public",
      "permissions": [
        "DELETE",
        "GET",
        "POST",
        "PUT"
      ]
    }
  ]
}

Listing Collection Keys

200 OK
Content-Type: application/json

{
  "keys": [
    {
      "name": "Primary Key",
      "key": "0b68f6e568ad37c16b92984cd961eae9",
      "master": false,
      "collection": "https://api-m2x.att.com/v2/collections/2373c20eabce36",
      "expires_at": null,
      "expired": false,
      "origin": null,
      "permissions": [
        "DELETE",
        "GET",
        "POST",
        "PUT"
      ]
    }
  ]
}

Create Key

POST /keys

Create a new key associated with the specified account. It takes the following parameters:

  • name will be the name of the new key
  • permissions should be an array of permissions for this key (see validations for more details)
  • device (optional) should be the ID of one of the user's Device, to create a key that can only access to this device.
  • distribution (optional) should be the ID of one of the user's Distribution, to create a key that can access any device in the distribution.
  • collection (optional) should be the ID of one of the user's Collection, to create a key that can access any device in the collection.
  • stream (optional) the stream name of one of the Stream that belongs to the device; in this case device is also required.
  • expires_at (optional) a string in ISO-8601 format.
  • origin (optional) a comma-separated list of IP addresses that are allowed to use this key.
  • device_access (optional - only applicable to master keys) whether this key should be able to access "private" or only "public" devices.

Only one of the following params can be passed when creating Keys: distribution, collection, device. If none of those are passed, the resulting key will be considered a Master Key. Once a key is created, their distribution, collection, device and stream attributes cannot be updated.

Request

Content-Type: application/json

{ "name": "newkey",
  "permissions": ["GET", "PUT"],
  "device": null,
  "stream": null,
  "expires_at": null }

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/keys/ab9702fe90c644d953cbe8817dfaa2a0

{
  "name": "New Key",
  "key": "ab9702fe90c644d953cbe8817dfaa2a0",
  "master": true,
  "expires_at": null,
  "expired": false,
  "origin": null,
  "device_access": "public",
  "permissions": [
    "GET",
    "PUT"
  ]
}

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one or more of these validations fail:

  • The key name must be specified (not_present).
  • The permissions field must be an array containing any combination of GET, PUT, POST and DELETE (not_valid).
  • device must be a valid Device ID or null (not_found).
  • distribution must be a valid distribution ID or null (not_found). It also cannot be present when a device or collection is also passed (not_valid).
  • collection must be a valid Collection ID or null (not_found). It also cannot be present when a device or distribution is also passed (not_valid).
  • stream must be a Stream name in the indicated device (not_found).
  • expires_at must be a string in ISO-8601 format or null (not_valid).
  • origin if provided, must be a comma-separated list of valid IP addresses (not_valid).
  • device_access if provided must be one of "public" or "private" (not_valid).

View Key Details

GET /keys/{key}

Get details of a specific key associated with a developer account.

Responses

Success

200 OK
Content-Type: application/json

{
  "name": "New Key",
  "key": "ab9702fe90c644d953cbe8817dfaa2a0",
  "master": true,
  "expires_at": null,
  "expired": false,
  "origin": null,
  "device_access": "public",
  "permissions": [
    "GET"
  ]
}

Key Not Found

404 Not Found
Content-Type: application/json

{ "message": "Key Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified key does not exist.

Update Key

PUT /keys/{key}

Update name, stream, permissions, expiration date, origin or device access of an existing key associated with the specified account.

Request

Content-Type: application/json

{ "name": "master",
  "permissions": ["GET"],
  "expires_at": "2014-10-03T15:37:05.000Z",
  "stream": "temperature",
  "origin": null,
  "device_access": "public" }

Responses

Success

204 No Content

Key Not Found

404 Not Found
Content-Type: application/json

{ "message": "Key Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified key does not exist.

Master API Key

403 Forbidden
Content-Type: application/json

{ "message": "Can't update primary master API Key", "description": "You cannot update your primary master API Key. Learn more about managing API keys at https://m2x.att.com/developer/documentation/overview#API-Keys" }

A developer will receive this response when trying to update the default Master API Key.

Validation Failed

422 Unprocessable Entity
Content-Type: application/json

{ "message": "Validation Failed",
  "errors": { "name": ["not_present"] } }

A developer will receive this response if one or more of these validations fail:

  • The key name must be specified (not_present).
  • The permissions field must be an array containing any combination of GET, PUT, POST and DELETE (not_valid).
  • device must be a valid Device ID or null (not_found).
  • distribution must be a valid distribution ID or null (not_found). It also cannot be present when a device or collection is also passed (not_valid).
  • collection must be a valid Collection ID or null (not_found). It also cannot be present when a device or distribution is also passed (not_valid).
  • stream must be a Stream name in the indicated device (not_found).
  • expires_at must be a string in ISO-8601 format or null (not_valid).
  • origin if provided, must be a comma-separated list of valid IP addresses (not_valid).
  • device_access if provided must be one of "public" or "private" (not_valid).

Regenerate Key

POST /keys/{key}/regenerate

Regenerate the specified key.

Responses

Success

201 Created
Content-Type: application/json
Location: https://api-m2x.att.com/v2/keys/fff092f2cb57b9b6196bd0e24c005958

{
  "name": "New Name",
  "key": "fff092f2cb57b9b6196bd0e24c005958",
  "master": true,
  "expires_at": null,
  "expired": false,
  "origin": null,
  "device_access": "public",
  "permissions": [
    "PUT"
  ]
}

Key Not Found

404 Not Found
Content-Type: application/json

{ "message": "Key Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified key does not exist.

Delete Key

DELETE /keys/{key}

Delete an existing key.

Responses

Success

204 No Content

Master API Key

403 Forbidden
Content-Type: application/json

{ "message": "Can't delete primary master API Key", "description": "You cannot delete your primary master API Key. Learn more about managing API keys at https://m2x.att.com/developer/documentation/overview#API-Keys" }

A developer will receive this response when trying to delete the default Master API Key.

Key Not Found

404 Not Found
Content-Type: application/json

{ "message": "Key Not Found", "description": "The resource you requested could not be found. Please verify that the correct resource path was provided, or refer to https://m2x.att.com/developer/documentation for complete API documentation." }

A developer will receive this response when the specified key does not exist.