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+ The easiest way to access the API is with a Personal Access Token (PAT)
31+ generated from the
32+ [Linode Cloud Manager](https://cloud.linode.com/profile/tokens). You must
33+ create a Personal Access Token to use the API. In most cases, a Personal
34+ Access Token is all you need to consume the API.
35+
36+ All scopes for the `oauth` security model (defined below) apply to this
37+ security model as well.
38+
39+ ## OAuth
40+
41+ The OAuth workflow is a three-step process to authenticate a user before an
42+ application can start making API calls on the user's behalf.
43+
44+ First, the user visits the application's website and is directed to log with
45+ Linode. The user is then redirected to Linode's authentication server and
46+ presented the scope levels the application is requesting. Once the user
47+ accepts the request for access, we redirect them back to the application's
48+ specified redirect URI with an access code.
49+
50+ Once the user has logged in to Linode and you have received an access code,
51+ you will need to exchange that access code for an Authorization token. You
52+ do this by making an HTTP POST request to the following address:
53+
54+ ```
55+ https://login.linode.com/oauth/token
56+ ```
57+
58+ Make this request as `application/x-www-form-urlencoded` or as
59+ `multipart/form-data` and include the following parameters in the POST body:
60+
61+ | PARAMETER | DESCRIPTION |
62+ |-----------|-------------|
63+ | client_id | Your app's client ID |
64+ | client_secret | Your app's client secret |
65+ | code | The code you just received from the redirect |
66+
67+ You'll get a reponse like this:
68+
69+ ```json
70+ {
71+ "scope": "linodes:create",
72+ "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c"
73+ "token_type": "bearer",
74+ "expires_in": 7200,
75+ }
76+ ```
3577
36- You can [view our Changelog](/changelog)
37- to keep up to date on all changes made to our API.
78+ Included is the actual access_token. With this token, you can proceed to make
79+ authenticated HTTP requests with the API by adding this header to each request:
80+
81+ ```
82+ Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c
83+ ```
84+
85+ ## Authentication Schema
86+
87+ See our [Authentication Schema](/#section/Authentication) for
88+ information on scopes and authorization/token URLs.
89+
90+ # Requests
91+
92+ Requests should be made over HTTPS to ensure transactions are encrypted.
93+
94+ | METHOD | USAGE |
95+ |--------|-------|
96+ | GET | Retrieves data about collections and individual resources. |
97+ | POST | For collections, creates a new resource of that type. Also used to perform actions on action endpoints. |
98+ | PUT | Updates an existing resource. |
99+ | DELETE | Deletes a resource. This is a destructive action. |
100+
101+
102+ # Responses
103+
104+ Actions will return one following HTTP response status codes:
105+
106+ | STATUS | DESCRIPTION |
107+ |---------|-------------|
108+ | 200 OK | The request was successful |
109+ | 204 No Content | The server successfully fulfilled the request and there is no additional content to send. |
110+ | 400 Bad Request | You submitted an invalid request (missing parameters, etc.). |
111+ | 401 Unauthorized | You failed to authenticate for this resource. |
112+ | 403 Forbidden | You are authenticated, but don't have permission to do this. |
113+ | 404 Not Found | The resource you're requesting does not exist. |
114+ | 429 Too Many Requests | You've hit a rate limit. |
115+ | 500 Internal Server Error | Please [open a Support Ticket](/#operation/createTicket). |
116+
117+ # Errors
118+
119+ Success is indicated via [Standard HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
120+ `2xx` codes indicate success, `4xx` codes indicate a request error, and
121+ `5xx` errors indicate a server error. A
122+ request error might be an invalid input, a required parameter being omitted,
123+ or a malformed request. A server error means something went wrong processing
124+ your request, and we'll fix it shortly. If this occurs, please
125+ [open a Support Ticket](/#operation/createTicket) and let us know.
126+
127+ The `errors` field is an array of the things that went wrong with your request.
128+ We will try to include as many of the problems in the response as possible,
129+ but it's conceivable that fixing these errors and resubmitting may result in
130+ new errors coming back once we are able to get further along in the process
131+ of handling your request.
132+
133+
134+ Within each error object, the `field` parameter will be included if the error
135+ pertains to a specific field in the JSON you've submitted. This will be
136+ omitted if there is no relevant field. The reason is a human-readable
137+ explanation of the error, and will always be included.
38138
39139 # Pagination
40140
@@ -162,51 +262,6 @@ info:
162262 ]
163263 }'
164264 ```
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) |
210265contact :
211266 name : Linode
212267 url : /
@@ -8079,9 +8134,9 @@ paths:
80798134 x-linode-grant : read_write
80808135 tags :
80818136 - support
8082- summary : Create Support Ticket
8137+ summary : Open Support Ticket
80838138 description : >
8084- Create a Support Ticket.
8139+ Open a Support Ticket.
80858140
80868141 Only one of the ID attributes (`linode_id`, `domain_id`, etc) can be set
80878142 on a single Support Ticket.
@@ -8092,14 +8147,14 @@ paths:
80928147 - oauth :
80938148 - account:read_write
80948149 requestBody :
8095- description : Create a Support Ticket.
8150+ description : Open a Support Ticket.
80968151 content :
80978152 application/json :
80988153 schema :
80998154 $ref : ' #/components/schemas/SupportTicketRequest'
81008155 responses :
81018156 ' 200 '
8102- description : Support Ticket created .
8157+ description : Support Ticket opened .
81038158 content :
81048159 application/json :
81058160 schema :
@@ -8786,15 +8841,11 @@ paths:
87868841lang : CLI
87878842 source : >
87888843 linode-cli volumes resize 12345 --size 30
8844+
87898845components :
87908846 securitySchemes :
87918847 personalAccessToken :
87928848 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.
87988849 scheme : bearer
87998850 oauth :
88008851 type : oauth2
0 commit comments