77 backgroundColor : ' #fafafa'
88 }
99 description : |
10- This is Linode's next generation API. The API was designed around the concepts of REST and does
11- its best to conform to a RESTful model whenever possible. When not possible the goal was to be
12- as intuitive as possible.
10+ The Linode API provides the ability to programmatically manage the full
11+ range of Linode products and services.
1312
14- Another design goal of the Linode API was to give developers the power to manipulate all Linode
15- services through code as easily as they can through the Linode Manager UI.
13+ This reference is designed to assist application developers and users.
14+ Each action (endpoint) includes descriptions, request syntax, and examples
15+ using standard HTTP requests. Response data is returned in JSON format.
1616
17- With this API, it is now not only possible to create a new Linode, but also enable backups,
18- add it to a Nodebalancer, attach Block Storage Volumes, create backup snapshots, imagize its
19- disk for mass deployment of more Linodes, and so much more.
2017
21- Additionally, as an administrator on an account, you can now use the API to create new users and
22- control the level of access they have to the services on your account.
18+ [Download the Linode OpenAPI Specification](/openapi.yaml)
2319
24- Finally, one of the most powerful features of this version of Linode's API is the ability to
25- allow third-party applications control of your account through the OAuth 2 protocol. All Linode
26- service endpoints allow four levels of access: __view__, __create__, __modify__, __delete__.
27- Developers now have the capability to create their own exciting new services on top of Linode's
28- world-class infrastructure.
2920
21+ # Changelog
3022
23+ [View our Changelog](/changelog) to keep up to date on all changes made to
24+ our API.
3125
32- [Download the Linode OpenAPI Specification](/openapi.yaml)
26+ # Access
3327
34- # Changelog
28+ ## Personal Access Token
29+
30+ You must request an access code that can then be exchanged for an
31+ authorization token. A Personal Access Token (PAT) is an
32+ [OAuth 2.0](https://oauth.net/2/) Access Token that you can generate via the
33+ [Linode Cloud Manager](https://cloud.linode.com/profile/tokens). You must
34+ create a Personal Access Token to use the API. If you are consuming the API
35+ for yourself only and do not intend on creating an application, a Personal
36+ Access Token is all you need.
37+
38+ The authorization token can then be used to make requests against our API.
39+
40+ All scopes for the `oauth` security model (defined below), apply to this
41+ security model as well.
42+
43+ ## OAuth
44+
45+ The OAuth workflow is a two-step process to authenticate a user before the
46+ user (or an application on the user's behalf) can start making API calls.
47+
48+ The user logs in to Linode and is presented the scope levels your
49+ application is requesting. Once the user accepts your request for access,
50+ we redirect them back to you with an access code. You may then exchange the
51+ access code for an authorization token.
52+
53+ Once the user has logged in to Linode and you have received an access code,
54+ you will need to exchange that access code for an Authorization token. You
55+ do this by making the following HTTP POST request:
56+
57+ ```
58+ https://login.linode.com/oauth/token
59+ ```
60+
61+ Make this request as `application/x-www-form-urlencoded` or as
62+ `multipart/form-data` and include the following parameters in the POST body:
63+
64+ | PARAMETER | DESCRIPTION |
65+ |-----------|-------------|
66+ | client_id | Your app's client ID |
67+ | client_secret | Your app's client secret |
68+ | code | The code you just received from the redirect |
69+
70+ You'll get a reponse like this:
71+
72+ ```json
73+ {
74+ "scope": "linodes:create",
75+ "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c"
76+ "token_type": "bearer",
77+ "expires_in": 7200,
78+ }
79+ ```
80+
81+ Included is the actual access_token. With this token, you can proceed to make
82+ authenticated HTTP requests with the API by adding this header to each request:
83+
84+ ```
85+ Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c
86+ ```
87+
88+ ## Authentication Schema
89+
90+ See our [Authentication Schema](/#section/Authentication) for
91+ information on scopes and authorization/token URLs.
3592
36- You can [view our Changelog](/changelog)
37- to keep up to date on all changes made to our API.
93+ # Requests
94+
95+ Requests should be made over HTTPS to ensure transactions are encrypted.
96+
97+ | METHOD | USAGE |
98+ |--------|-------|
99+ | GET | Retrieves data about collections and individual resources. |
100+ | POST | Creates a new resource, such as a Linode Instance, NodeBalancer, Volume, etc. |
101+ | PUT | Updates an existing resource. |
102+ | DELETE | Deletes a resource. In virtually all cases this is a destructive action. |
103+
104+
105+ # Responses
106+
107+ Actions will return one following HTTP response status codes:
108+
109+ | STATUS | DESCRIPTION |
110+ |---------|-------------|
111+ | 200 OK | The request was successful |
112+ | 400 Bad Request | You submitted an invalid request (missing parameters, etc.). |
113+ | 401 Unauthorized | You failed to authenticate for this resource. |
114+ | 403 Forbidden | You are authenticated, but don't have permission to do this. |
115+ | 404 Not Found | The resource you're requesting does not exist. |
116+ | 429 Too Many Requests | You've hit a rate limit. |
117+ | 500 Internal Server Error | Please [open a Support Ticket](/#operation/createTicket). |
118+
119+ # Errors
120+
121+ Success is indicated via [Standard HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
122+ `2xx` codes indicate success, `4xx` codes indicate an
123+ error on your side, and `5xx` errors indicate an error on our side. An error
124+ on your side might be an invalid input, a required parameter being omitted,
125+ etc. Errors on our side shouldn't happen often. If an error does occur, please
126+ let us know.
127+
128+ Requests that return errors will look like this:
129+
130+ ```Shell
131+ {
132+ "errors": [
133+ {
134+ "reason": "Invalid JSON"
135+ }
136+ ]
137+ }
138+ ```
139+
140+ The `errors` field is an array of the things that went wrong with your request.
141+ We will try to include as many of the problems in the response as possible,
142+ but it's conceivable that fixing these errors and resubmitting may result in
143+ new errors coming back once we are able to get further along in the process
144+ of handling your request.
145+
146+
147+ Within each error object, the `field` parameter will be included if the error
148+ pertains to a specific field in the JSON you've submitted. This will be
149+ omitted if there is no relevant field. The reason is a human-readable
150+ explanation of the error, and will always be included.
38151
39152 # Pagination
40153
@@ -162,51 +275,6 @@ info:
162275 ]
163276 }'
164277 ```
165-
166- # Errors
167-
168- Success is indicated via [Standard HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
169- `2xx` codes indicate success, `4xx` codes indicate an
170- error on your side, and `5xx` errors indicate an error on our side. An error
171- on your side might be an invalid input, a required parameter being omitted,
172- etc. Errors on our side shouldn't happen often. If an error does occur, please
173- let us know.
174-
175- Requests that return errors will look like this:
176-
177- ```Shell
178- {
179- "errors": [
180- {
181- "reason": "Invalid JSON"
182- }
183- ]
184- }
185- ```
186-
187- The `errors` field is an array of the things that went wrong with your request.
188- We will try to include as many of the problems in the response as possible,
189- but it's conceivable that fixing these errors and resubmitting may result in
190- new errors coming back once we are able to get further along in the process
191- of handling your request.
192-
193-
194- Within each error object, the `field` parameter will be included if the error
195- pertains to a specific field in the JSON you've submitted. This will be
196- omitted if there is no relevant field. The reason is a human-readable
197- explanation of the error, and will always be included.
198-
199- # HTTP Status Codes
200-
201- | STATUS | DESCRIPTION |
202- |---------|-------------|
203- | 200 OK | The request was successful |
204- | 400 Bad Request | You submitted an invalid request (missing parameters, etc.) |
205- | 401 Unauthorized | You failed to authenticate for this resource |
206- | 403 Forbidden | You are authenticated, but don't have permission to do this |
207- | 404 Not Found | The resource you're requesting does not exist |
208- | 429 Too Many Requests | You've hit a rate limit |
209- | 500 Internal Server Error | Please [open a Support Ticket](/#operation/createTicket) |
210278contact :
211279 name : Linode
212280 url : /
@@ -8079,9 +8147,9 @@ paths:
80798147 x-linode-grant : read_write
80808148 tags :
80818149 - support
8082- summary : Create Support Ticket
8150+ summary : Open Support Ticket
80838151 description : >
8084- Create a Support Ticket.
8152+ Open a Support Ticket.
80858153
80868154 Only one of the ID attributes (`linode_id`, `domain_id`, etc) can be set
80878155 on a single Support Ticket.
@@ -8092,14 +8160,14 @@ paths:
80928160 - oauth :
80938161 - account:read_write
80948162 requestBody :
8095- description : Create a Support Ticket.
8163+ description : Open a Support Ticket.
80968164 content :
80978165 application/json :
80988166 schema :
80998167 $ref : ' #/components/schemas/SupportTicketRequest'
81008168 responses :
81018169 ' 200 '
8102- description : Support Ticket created .
8170+ description : Support Ticket opened .
81038171 content :
81048172 application/json :
81058173 schema :
@@ -8785,16 +8853,12 @@ paths:
87858853 https://api.linode.com/v4/volumes/12345/resize
87868854lang : CLI
87878855 source : >
8788- linode-cli volumes resize 12345 --size 30
8856+ linode-cli volumes resize 12345 --size 301
8857+
87898858components :
87908859 securitySchemes :
87918860 personalAccessToken :
87928861 type : http
8793- description : |
8794- A Personal Access Token is an OAuth 2.0 Access Token that you can generate for your own
8795- personal use through the [Linode Cloud Manager](https://cloud.linode.com/profile/tokens).
8796-
8797- All scopes defined for the `oauth` security model, apply to this security model as well.
87988862 scheme : bearer
87998863 oauth :
88008864 type : oauth2
0 commit comments