API: API Application Key

From Yombo
Jump to: navigation, search

Summary

An API Application Key is used to authorize applications, this is separate from the user. This allows Yombo to revoke applications access to the API if they are behaving badly.

The API App Key (AKA: API Key) must be sent with all requests for the service to accept the request. There are two methods to submit the API App Key:

  1. In the HTTP request header as: x-api-app-key
    • Alternatives include: x-api-key, x_api_app_key, x_api_key, and api_app_key
    • Example: x-api-key: abc123xyz789
  2. In the query string, use any of the above names as a query string parameter.
    • Example: https://api.yombo.net/api/v1/commands?x-api-app-key=abc123xyz789

You must replace abc123xyz789 with a valid API App Key.

Currently, you can request an API key by emailing support at yombo.net with a description for the usage of the API key. The ability to add API Keys through my.yombo.net is planned.

The API key is not used to authenticate the user, only the application. For authentication, see API Authentication to authenticate the user.

Example

  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
/api/v1/commands?page[size]=3
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/commands?page[size]=3'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "data": [
 3         {
 4             "type": "commands",
 5             "id": "6a7ylqea1LsDqXb8V",
 6             "attributes": {
 7                 "id": "6a7ylqea1LsDqXb8V",
 8                 "voice_cmd": "on",
 9                 "machine_label": "on",
10                 "label": "On",
11                 "description": "Sends an on command",
12                 "public": 2,
13                 "status": 1,
14                 "created_at": 1482065387,
15                 "updated_at": 1518130546
16             },
17             "links": {
18                 "self": "https://api.yombo.net/api/v1/commands/6a7ylqea1LsDqXb8V"
19             }
20         },
21         {
22             "type": "commands",
23             "id": "pVZQKBgg5aI3BglM7",
24             "attributes": {
25                 "id": "pVZQKBgg5aI3BglM7",
26                 "voice_cmd": "off",
27                 "machine_label": "off",
28                 "label": "Off",
29                 "description": "Sends an off command",
30                 "public": 2,
31                 "status": 1,
32                 "created_at": 1482065387,
33                 "updated_at": 1482065387
34             },
35             "links": {
36                 "self": "https://api.yombo.net/api/v1/commands/pVZQKBgg5aI3BglM7"
37             }
38         },
39         {
40             "type": "commands",
41             "id": "pVZQKBg9yzTd0glM7",
42             "attributes": {
43                 "id": "pVZQKBg9yzTd0glM7",
44                 "voice_cmd": "close",
45                 "machine_label": "close",
46                 "label": "Close",
47                 "description": "Sends a close command",
48                 "public": 2,
49                 "status": 1,
50                 "created_at": 1482065387,
51                 "updated_at": 1482065387
52             },
53             "links": {
54                 "self": "https://api.yombo.net/api/v1/commands/pVZQKBg9yzTd0glM7"
55             }
56         }
57     ],
58     "meta": {
59         "count": 3,
60         "current_page": 1,
61         "from": 1,
62         "last_page": 12,
63         "path": "https://api.yombo.net/api/v1/commands",
64         "per_page": 3,
65         "to": 3,
66         "total": 34,
67         "includable": [
68             "users"
69         ]
70     },
71     "links": {
72         "first": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=1",
73         "last": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=12",
74         "prev": null,
75         "next": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=2",
76         "self": "https://api.yombo.net/api/v1/commands"
77     }
78 }
This page was last edited on 12 April 2019.