API Key Resource

An api_key resource defines a secret key that is used to authenticate API calls. A single api_key secret key can grant rights to the entire API or it can be defined to only grant one specific action to a specific resource from a specific IP address.


The api_key resource is used by devices to:

• Prevent hard-coding of a user email address and password
• To avoid session timeouts
• To only grant the rights a specific device needs in case the secret key becomes compromised

The api_key secret key is passed to the server a token, either as a URI argument or as a cookie. Be aware that if a session token is passed with an api_key secret key, the session will be used for authentication and determining access rights.

An api_key can be generated with the GroveStreams API or it can be generated by a GroveStreams owner in the website. The owner can copy the secret key from the website to the clipboard and then use the secret key from within the code calling the GroveStreams API.

The api_key server architecture is very scalable. An organization can have many keys, one per component or stream, if that's what their security demands require. Each api_key is limited to 2,000 specific resource references.

Child resources inherit their parent's rights. There can exist a condition where a parent resource has certain rights but one or more of its children has other rights set. For example, GET only rights might be given to all component entities, but then GET, DELETE, PUT, POST rights might be given to one specific stream. When rights are given to a child resource those rights will override any parent rights. For the previous example, GET rights will be allowed for all streams except the specified stream will have GET, DELETE, PUT, POST rights.

Valid Actions are no actions ("") or:

• GET
• PUT
• POST
• DELETE

IP addresses are comma delimited.

Only GroveStreams ADMIN and OWNER users have rights to generate or modify api_keys but be aware that the owner could create an api_key that can grant rights to the api for non ADMIN users.

api_key Examples

GET api_key

---

Returns a list of api_key resources.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

Parameters

none

Example Requests

/api_key

Response Body

{
  "message": "",
  "success": true,
  "apiKey": [
    {
      "uid": "0251247b-7dd8-4bf9-81fe-fda7b92b4fc2",
      "name": "key 1"
    },
    {
      "uid": "045c852e-f2fa-4675-8f21-15f38085b65f",
      "name": "key 2"
    },
    {
      "uid": "05ece216-63e2-4917-b930-bd18961276b2",
      "name": "key 3"
    }
  ]
}

GET api_key/{api_keyUid}

---

Returns a api_key with the specified uid.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible?	Yes

Parameters

none

Example Requests

This example returns an api_key resource. It allows all actions to all units and GET actions for all streams of a specific component. Only calls from the list of addresses will be accepted for this api_key

/api_key/181085f9-cfac-48db-b392-3983b020e12b

Response Body

{
  "message": "",
  "success": true,
  "apiKey": {
    "uid": "181085f9-cfac-48db-b392-3983b020e12b",
    "name": "key 1",
    "addresses": "174.53.181.105,174.54.181.106,174.55.181.107",
    "resource": [
      {
        "item": "unit/",
        "actions": "PUT,POST,DELETE,GET"
      },
      {
        "uid": "",
        "name": "",
        "item": "component/8d6bb905-0e71-4321-9b0c-f8fe85cbc77f/stream/",
        "actions": "GET"
      }
    ]
  }
}

GET api_key/{api_keyUid}/secret_key

---

Returns the secret key for an api_key.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible?	Yes

Parameters

none

Example Requests

This example returns an api_key's secret_key.

/api_key/05140147-0c58-4886-a6f4-ec05d29b7ae6

Response Body

{
  "message": "",
  "success": true,
  "apiKey": {
    "secretKey": "05140147-0c58-4886-a6f4-ec05d29b7ae6"
  }
}

GET api_key/new

---

Returns a default api_key with a unique UID. Does not persist the new api_key in the store. It's the callers responsibility to PUT the new api_key and register it.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Parameters

none

Example Requests

/api_key/new

Response Body
{
  "apiKey": {
    "uid": "181085f9-cfac-48db-b392-3983b020e12b",
    "name": "",
    "addresses": "",
    "resource": [
     
    ]
  }
}

PUT api_key

---

Inserts a new api_key. The uid of the api_key can be blank. If it is blank a uid will be created on the server and the response body will contain the new uid. Addresses and actions are comma delimited. A blank address indicates all addresses can make the call. A blank actions indicate no actions are allowed for the resource(s).	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Parameters

none

Example Requests

Request Body {
  "api_key": {
    "uid": "",
    "resource": [
      {
        "item": "component",
        "actions": "GET"
      }
    ],
    "name": "GET all components",
    "addresses": ""
  }
}

Response Body
{
  "message": "Inserted api_key with uid '779a018a-f6c7-493b-ba3c-cf5bc47bbdef'",
  "api_key": {
    "uid": "779a018a-f6c7-493b-ba3c-cf5bc47bbdef",
    "name": "GET all components",
    "resource": [
      {
        "item": "component",
        "actions": "GET"
      }
    ],
    "addresses": ""
  },
  "success": true
}

POST api_key

---

Used to update an existing api_key. Addresses and actions are comma delimited. A blank address indicates all addresses can make the call. A blank actions indicate no actions are allowed for the resource(s)	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Parameters

none

Example Requests

/api_key

Request Body
{
  "api_key": {
    "uid": "779a018a-f6c7-493b-ba3c-cf5bc47bbdef",
    "resource": [
      {
        "item": "component",
        "actions": "GET,PUT,POST,DELETE"
      }
    ],
    "name": "GET all components",
    "addresses": ""
  }
}

Response Body
{
  "message": "Updated api_key with uid '779a018a-f6c7-493b-ba3c-cf5bc47bbdef'",
  "api_key": {
    "uid": "779a018a-f6c7-493b-ba3c-cf5bc47bbdef",
    "name": "GET all components",
    "resource": [
      {
        "item": "component",
        "actions": "GET,PUT,POST,DELETE"
      }
    ],
    "addresses": ""
  },
  "success": true
}

DELETE api_key/{api_keyUid}

---

Deletes a api_key.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Parameters

none

Example Requests

/api_key/d251a8f2-f7b9-4df7-886d-b24c7f4929d4

Response Body
{
    "message" : "Deleted api_key with uid 'd251a8f2-f7b9-4df7-886d-b24c7f4929d4
    "success" : true
}