-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathauthentication.apib
98 lines (64 loc) · 4.62 KB
/
authentication.apib
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
FORMAT: 1A
HOST: https://passport.thegrid.io/
# Authentication
The Grid operates an OAuth2 provider that is utilized for all authentication purposes.
### Identity Providers
The Grid's authentication system supports multiple identity providers including:
* Facebook (facebook)
* GitHub (github)
* Google (google)
* Twitter (twitter)
More identity providers are likely to be added later when they are needed. Check back to this document to see the current list.
### Registering an application
The Grid authentication is always granted to the combination of a user and an application. To register an application, log into your The Grid account at https://passport.thegrid.io/account
Go to the Developer Section of your profile page, and you'll be able to add new OAuth2 client applications. You need the following information:
* Application name: name of the application shown to users in the confirmation page
* Callback URL: the URL in your application users should be redirected to once they complete their login
Once you have registered an application you will get two values from the system:
* Application ID: Unique identifier for your application
* Application secret: Passphrase your application can use to convert authentication grants to tokens
**Note:** never let others see your client secret. Otherwise they will be able to impersonate your The Grid application!
### The OAuth dance
When you want to authenticate a user with your The Grid application, you need to first send them to The Grid's login system. For this you need to construct a login URL with the following parts:
* Protocol: https
* Host: passport.thegrid.io
* Path: `/login/authorize/<identity provider (optional, otherwise will show UI to choose provider)>`
* Query:
* `client_id`: the unique identifier of your application
* `response_type`: code
* `scope`: comma-separated list of requested scopes
* `redirect_uri`: your callback URL
Example: <https://passport.thegrid.io/login/authorize/github?client_id=XXXX&response_type=code&scope=share&redirect_uri=http://my.app.url>
#### Authentication scopes
The default authentication scope will grant you permissions to perform simple operations on behalf of the user. If needed, you can also request additional access to The Grid APIs via OAuth2 scopes. The scopes are added to the authentication request URL with the scope query key.
The currently supported scopes include:
* `content_management`: manage user's content items on The Grid
* `website_management`: manage user's The Grid sites and publish to them
* `share`: share new content to The Grid. Also provided by the `content_management` scope
* `update_profile`: update the user's profile information
* `github`: get access to the user's GitHub access token, if any. This will allow you to use the GitHub API on behalf of the user
* `github_private`: get access to the user's GitHub access token authorized to access private repositories, if any. This will allow you to use the GitHub API on behalf of the user
* `payment`: make a payment on behalf of the user
* `balance`: see user's account balance and transaction history
* `cta_management`: manage user's Calls to Action
#### Getting a token
Once the user completes the authentication process and grants your application access to their account, they will be redirected to the redirect_uri.
The redirection will contain an additional query parameter code which contains a one-time access grant.
To convert this access grant to an access token you have to make a HTTP POST request with the following URL:
* Protocol: https
* Host: passport.thegrid.io
* Path: /login/authorize/token
The payload should be a URL-encoded string containing the following key-value pairs:
* `client_id`: the unique identifier of your application
* `client_secret`: your application's passphrase
* `code`: the access grant you received in the query parameter of your callback URL
* `grant_type`: `authorization_code`
On a successful code conversion you will receive a JSON-encoded response with an object that will contain the user's access token in the `access_token` key.
### Making authenticated API requests
The Grid API calls require authentication unless stated otherwise. This is done using the user's access token via HTTP Bearer Authentication. Bearer authentication works by adding the Authorization header to your HTTP requests with the value `Bearer <access token>`.
For example:
```
req.setRequestHeader('Authorization', 'Bearer ' + token);
```
### The Grid authentication on Node.js
The [passport-thegrid](https://www.npmjs.com/package/passport-thegrid) module provides The Grid authentication for [Passport](http://passportjs.org/) enabled Node.js applications.