API: Authentication

From Yombo
Jump to: navigation, search

Overview

User authentication is required for most requests the API. The authentication can be provided in the Authorization HTTP request header. To get an authorization token for an application or script, you'll need to visit My.Yombo.Net.

Getting Authentication Token

Before making requests to the API, you'll need to visit My.Yombo.Net to get a token. Follow these steps to complete this:

  1. Visit My.Yombo.Net.
  2. Login if you haven't already.
  3. In the upper right corner, click on your name.
  4. From the drop down menu, select 'Your Settings'.
  5. On the right side, select API.
  6. Select a token name to help you remember where the token is used. For example 'Garage door script', 'Postman', or 'Device monitor script'.
  7. The 'Token Can' allows you to restrict what the token can be used for. For example, if you only want to read devices, select 'Device - View'. At least one permission must be included.
    • Permissions can be updated at a later time if desired.
  8. Click on create.
  9. A pop-up window will be shown displaying the new API Token. Copy this token to a safe place.
    • Important: The API Token cannot be recovered. If the token is lost, you must request another token. Simply delete this current token and create another one.

Be sure to protect this token. It allows access to your account and any permissions you granted this token. A token can be revoked as need.

Revoking Tokens

The process to revoke a token is much like creating them:

  1. Visit My.Yombo.Net.
  2. Login if you haven't already.
  3. In the upper right corner, click on your name.
  4. From the drop down menu, select 'Your Settings'.
  5. On the right side, select API.
  6. Find the token you wish revoke and click on the red X.
  7. From the pop-up dialog box, confirm token deletion.

Usage

To use the authentication token, you must set the header 'Authorization' to: 'Bearer api_token' Replace the value of api_token with the token you received from My.Yombo.Net.

  <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.