-
Notifications
You must be signed in to change notification settings - Fork 21
/
index.html
119 lines (116 loc) · 5.93 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
{% extends "base.html" %}
{% block main %}
<div class="content">
<div class="content-developer">
<h1>Hey Developers!</h1>
<p>
<a href="/developers/apps">Your Apps</a>
</p>
<h2>Steps To Creating A MLTSHP Application</h2>
<p>
To get started first <a href="/developers/new-api-application">register an application</a>. You'll need to
enter a title, description, and also a redirect URL.
This URL will be where users of your app will be sent after approving your app to access their account.
</p>
Once that is done you will be given an API key and a secret. We are using draft 12 of the new <b>OAuth2</b> specification.
If you want to read the gory details they are all here: <a href="http://tools.ietf.org/html/draft-ietf-oauth-v2-12">http://tools.ietf.org/html/draft-ietf-oauth-v2-12</a>.
</p>
<p>
The steps are:
</p>
<ul>
<li>Provide a MLTSHP authentication URL for your user to approve your application's access. (http://mysite.com/return)</li>
<li>Capture the authorization code when they are bounced back to your site. (http://mysite.com/return?code=######)</li>
<li>Use that authorization code to request an access token. The access token will contain a key and a secret.</li>
<li>Use the key to make requests on behalf of your user and sign each request with the secret. </li>
<li>If the request is properly signed you can request resources and make updates to those resources on behalf of the user.</li>
</ul>
<h3>Signing API Requests</h3>
<p>
To sign a request to the API, you'll need to add an <code>Authorization</code> header to your request.
The value of that header is the authorization string. Start by constructing the signature string:
</p>
<pre><code>${TIMESTAMP}
${NONCE}
${METHOD}
mltshp.com
${PORT}
${PATH}
${QUERY}</code></pre>
<ul>
<li><strong>timestamp</strong> is a UTC timestamp in seconds.</li>
<li><strong>nonce</strong> is a random string between 10 and 35 characters long.</li>
<li><strong>method</strong> either <code>GET</code> or <code>POST</code>.</li>
<li><strong>host</strong> is <code>mltshp.com</code>.</li>
<li><strong>port</strong> should be <code>443</code> for SSL, but there's a bug in the API right now, and you'll have to use <code>80</code>.</li>
<li><strong>path</strong> is the API endpoint you're fetching, such as <code>/api/sharedfile/GA4</code>.</li>
<li><strong>query</strong> any parameters for a <code>POST</code> request. Leave blank for <code>GET</code> requests.</li>
</ul>
<p>
Once you've constructed that signature string, you'll need to encode it into an HMAC-SHA1 hash using the <code>secret</code> value from the <code>token</code> object. Then Base64 encode the hash.
</p>
<p>Now you can construct the authorization string:</p>
<pre><code>MAC token=${TOKEN}, timestamp=${TIMESTAMP}, nonce=${NONCE}, signature=${SIGNATURE}</code></pre>
<ul>
<li><strong>token</strong> is the <code>access_token</code> value of the <code>token</code> object.</li>
<li><strong>timestamp</strong> needs to match the <code>timestamp</code> in the signature.</li>
<li><strong>nonce</strong> needs to match the <code>nonce</code> in the signature.</li>
<li><strong>signature</strong> is the encoded signature string you just built.</li>
</ul>
<p>Set this authorization string as the value of the <code>Authorization</code> header in your API request.</p>
<h2>Example Scripts</h2>
<p>
Here are some example scripts. They require you to input your access key and secret you get
from <a href="/developers/apps">creating an application here</a>.
</p>
<ul>
<li><a href="/static/developers/example.py.txt">Python Script</a></li>
<li><a href="/static/developers/example.php.txt">PHP Script</a></li>
<li><a href="https://github.com/spaceninja/mltshp-api-test-js">JavaScript</a></li>
</ul>
<a name='desktop'></a>
<h2>Desktop or Mobile Device App</h2>
<p>
Here is how to authenticate in one step when using a desktop or iOS application. Instead of sending the user
to a web page to approve, and then have them return to your application with an auth code, you can get
an access token with one step. <strong>DO NOT</strong> use this method if you are not making a desktop application.
</p>
<p>
After acquiring <a href="/developers/new-api-application">app credentials here</a>, POST
the following data here:
</p>
<pre>
/api/token?grant_type=<strong>password</strong>&client_id=<strong>your app key</strong>
&client_secret=<strong>your app secret</strong>&username=<strong>the user's name</strong>&password=<strong>the user's password</strong>
</pre>
<p>
Then if everything matches you'll receive an access token as a JSON response:
</p>
<pre>
{
"access_token": "########",
"secret": "########",
"token_type": "mac",
"algorithm": "hmac-sha-1"
}</pre>
<p>
Please be aware that your parameters should be url encoded. This is a command line example using curl:
</p>
<pre>
curl \
--data-urlencode "grant_type=<strong>password</strong>" \
--data-urlencode "client_id=<strong>your app key</strong>" \
--data-urlencode "client_secret=<strong>your app secret</strong>" \
--data-urlencode "username=<strong>the user's name</strong>" \
--data-urlencode "password=<strong>the user's password</strong>" \
-s -X POST "https://mltshp.com/api/token"
</pre>
<p>
Requests to the API should be signed with the access token as normal in the above script examples.
</p>
<h2>API Reference</h2>
<p>See the <a href="/developers/reference">reference documentation here</a>.</p>
<p><a href="https://www.fastly.com"><img src="/static/images/fastly-logo.png"></a> Proudly powered by Fastly.</p>
</div>
</div>
{% end %}