Linode API (4.0.8)

Introduction

The Linode API provides the ability to programmatically manage the full range of Linode products and services.

This reference is designed to assist application developers and system administrators. Each endpoint includes descriptions, request syntax, and examples using standard HTTP requests. Response data is returned in JSON format.

This document was generated from our OpenAPI Specification. See the OpenAPI website for more information.

Download the Linode OpenAPI Specification

Changelog

View our Changelog to see release notes on all changes made to our API.

Access and Authentication

Some endpoints are publicly accessible without requiring authentication. All endpoints affecting your Account, however, require either a Personal Access Token or OAuth authentication (when using third-party applications).

Personal Access Token

The easiest way to access the API is with a Personal Access Token (PAT) generated from the Linode Cloud Manager.

All scopes for the OAuth security model (defined below) apply to this security model as well.

Authentication

Security Scheme Type: HTTP
HTTP Authorization Scheme bearer

OAuth

The OAuth workflow is a three-step process to authenticate a User before an application can start making API calls on the User's behalf. If all you need is a Personal Access Token, feel free to skip ahead to the next section.

First, the User visits the application's website and is directed to log with Linode. The User is then redirected to Linode's authentication server and presented the scope levels the application is requesting. Once the User accepts the request for access, we redirect them back to the application's specified redirect URI with an access code.

Once the User has logged in to Linode and you have received an exchange code, you will need to exchange that access code for an Authorization token. You do this by making an HTTP POST request to the following address:

https://login.linode.com/oauth/token

Make this request as application/x-www-form-urlencoded or as multipart/form-data and include the following parameters in the POST body:

PARAMETER DESCRIPTION
client_id Your app's client ID
client_secret Your app's client secret
code The code you just received from the redirect

You'll get a reponse like this:

{
  "scope": "linodes:read_write",
  "access_token": "03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c"
  "token_type": "bearer",
  "expires_in": 7200,
}

Included in the reponse is access_token. With this token, you can proceed to make authenticated HTTP requests to the API by adding this header to each request:

Authorization: Bearer 03d084436a6c91fbafd5c4b20c82e5056a2e9ce1635920c30dc8d81dc7a6665c

Authentication

Security Scheme Type: Oauth2
AuthorizationCode Oauth Flow Authorization URL: https://login.linode.com/oauth/authorize
Token URL: https://login.linode.com/oauth/token
Scopes:
  • account:read_only - Allows access to GET information about your Account.
  • account:read_write - Allows access to all endpoints related to your Account.
  • domains:read_only - Allows access to GET Domains on your Account.
  • domains:read_write - Allows access to all Domain endpoints.
  • events:read_only - Allows access to GET your Events.
  • events:read_write - Allows access to all endpoints related to your Events.
  • images:read_only - Allows access to GET your Images.
  • images:read_write - Allows access to all endpoints related to your Images.
  • ips:read_only - Allows access to GET your ips.
  • ips:read_write - Allows access to all endpoints related to your ips.
  • linodes:read_only - Allows access to GET Linodes on your Account.
  • linodes:read_write - Allow access to all endpoints related to your Linodes.
  • longview:read_only - Allows access to GET your Longview Clients.
  • longview:read_write - Allows access to all endpoints related to your Longview Clients.
  • nodebalancers:read_only - Allows access to GET NodeBalancers on your Account.
  • nodebalancers:read_write - Allows access to all NodeBalancer endpoints.
  • stackscripts:read_only - Allows access to GET your StackScripts.
  • stackscripts:read_write - Allows access to all endpoints related to your StackScripts.
  • volumes:read_only - Allows access to GET your Volumes.
  • volumes:read_write - Allows access to all endpoints related to your Volumes.

Requests

Requests must be made over HTTPS to ensure transactions are encrypted. The following Request methods are supported:

METHOD USAGE
GET Retrieves data about collections and individual resources.
POST For collections, creates a new resource of that type. Also used to perform actions on action endpoints.
PUT Updates an existing resource.
DELETE Deletes a resource. This is a destructive action.

Responses

Actions will return one following HTTP response status codes:

STATUS DESCRIPTION
200 OK The request was successful.
204 No Content The server successfully fulfilled the request and there is no additional content to send.
400 Bad Request You submitted an invalid request (missing parameters, etc.).
401 Unauthorized You failed to authenticate for this resource.
403 Forbidden You are authenticated, but don't have permission to do this.
404 Not Found The resource you're requesting does not exist.
429 Too Many Requests You've hit a rate limit.
500 Internal Server Error Please open a Support Ticket.

Errors

Success is indicated via Standard HTTP status codes. 2xx codes indicate success, 4xx codes indicate a request error, and 5xx errors indicate a server error. A request error might be an invalid input, a required parameter being omitted, or a malformed request. A server error means something went wrong processing your request. If this occurs, please open a Support Ticket and let us know. Though errors are logged and we work quickly to resolve issues, opening a ticket and providing us with reproducable steps and data is always helpful.

The errors field is an array of the things that went wrong with your request. We will try to include as many of the problems in the response as possible, but it's conceivable that fixing these errors and resubmitting may result in new errors coming back once we are able to get further along in the process of handling your request.

Within each error object, the field parameter will be included if the error pertains to a specific field in the JSON you've submitted. This will be omitted if there is no relevant field. The reason is a human-readable explanation of the error, and will always be included.

Pagination

Resource lists are always paginated. The response will look similar to this:

{
    "data": [ ... ],
    "page": 1,
    "pages": 3,
    "results": 300
}

Pages start at 1. You may retrieve a specific page of results by adding ?page=x to your URL (for example, ?page=4). Page sizes default to 100, and can be set to return between 25 and 100. Page size can be set using ?page_size=x.

Filtering and Sorting

Collections are searchable by fields they include, marked in the spec as x-linode-filterable: true. Filters are passed in the X-Filter header and are formatted as JSON objects. Here is a request call for Linode Types in our "standard" class:

curl "https://api.linode.com/v4/linode/types" \
  -H 'X-Filter: { \
    "class": "standard"
  }'

The filter object's keys are the keys of the object you're filtering, and the values are accepted values. You can add multiple filters by including more than one key. For example, filtering for "standard" Linode Types that offer one vcpu:

 curl "https://api.linode.com/v4/linode/types" \
  -H 'X-Filter: { \
    "class": "standard",
    "vcpus": 1
  }'

In the above example, both filters are combined with an "and" operation. However, if you wanted either Types with one vcpu or Types in our "standard" class, you can add an operator:

curl "https://api.linode.com/v4/linode/types" \
  -H 'X-Filter: {
    "+or": [
      { "vcpus": 1 },
      { "class": "standard" }
    ]
  }'

Each filter in the +or array is its own filter object, and all conditions in it are combined with an "and" operation as they were in the previous example.

Other operators are also available. Operators are keys of a Filter JSON object. Their value must be of the appropriate type, and they are evaluated as described below:

OPERATOR TYPE DESCRIPTION
+and array All conditions must be true.
+or array One condition must be true.
+gt number Value must be greater than number.
+gte number Value must be greater than or equal to number.
+lt number Value must be less than number.
+lte number Value must be less than or equal to number.
+contains string Given string must be in the value.
+neq string Does not equal the value.
+order_by string Attribute to order the results by - must be filterable.
+order string Either "asc" or "desc". Defaults to "asc". Requires +order_by.

For example, filtering for Linode Types that offer memory equal to or higher than 61440:

curl "https://api.linode.com/v4/linode/types" \
  -H 'X-Filter: {
    "memory": {
      "+gte": 61440
    }
  }'

You can combine and nest operators to construct arbitrarily-complex queries. For example, give me all Linode Types which are either standard or highmem class, and have between 12 and 20 vcpus:

curl "https://api.linode.com/v4/linode/types" \
  -H 'X-Filter: {
    "+or": [
      {
        "+or": [
          {
            "class": "standard"
          },
          {
            "class": "highmem"
          }
        ]
      },
      {
        "+and": [
          {
            "vcpus": {
              "+gte": 12
            }
          },
          {
            "vcpus": {
              "+lte": 20
            }
          }
        ]
      }
    ]
  }'

CLI (Command Line Interface)

The Linode CLI allows you to easily work with the API using intuitive and simple syntax. It requires a Personal Access Token for authentication, and gives you access to all of the features and functionality of the Linode API that are documented here with CLI examples.

Endpoints that do not have CLI examples are currently unavailable through the CLI, but can be accessed via other methods such as Shell commands and other third-party applications.

Account

View Account

get /account
https://api.linode.com/v4/account

Returns the contact and billing information related to your Account.

Authorizations:
oauth (account:read_only)

Responses

200

Returns a single Account object.

Response Schema: application/json
email
string <= 128 characters

The email address of the person associated with this Account.

address_1
string <= 64 characters

First line of this Account's billing address.

balance
number

This Account's balance, in US dollars.

city
string <= 24 characters

The city for this Account's billing address.

credit_card
object

Credit Card information associated with this Account.

company
string <= 128 characters

The company name associated with this Account.

country
string 2 characters

The two-letter country code of this Account's billing address.

address_2
string <= 64 characters

Second line of this Account's billing address.

first_name
string <= 50 characters

The first name of the person associated with this Account.

last_name
string <= 50 characters

The last name of the person associated with this Account.

phone
string <= 32 characters

The phone number associated with this Account.

state
string <= 24 characters

If billing address is in the United States, this is the State portion of the Account's billing address. If the address is outside the US, this is the Province associated with the Account's billing address.

tax_id
string <= 100 characters

The tax identification number associated with this Account, for tax calculations in some countries. If you do not live in a country that collects tax, this should be null.

zip
string <= 16 characters

The zip code of this Account's billing address.

default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account

Response samples

application/json
Copy
Collapse all Expand all
{
  • "address_1": "123 Main Street",
  • "address_2": "Suite A",
  • "balance": 200,
  • "city": "Philadelphia",
  • "credit_card":
    {
    • "last_four": 1111,
    • "expiry": "11/2022"
    },
  • "company": "Linode LLC",
  • "country": "US",
  • "email": "john.smith@linode.com",
  • "first_name": "John",
  • "last_name": "Smith",
  • "phone": "215-555-1212",
  • "state": "Pennsylvania",
  • "tax_id": "ATU99999999",
  • "zip": 19102
}

Update Account

put /account
https://api.linode.com/v4/account

Updates contact and billing information related to your Account.

Authorizations:
oauth (account:read_write)
Request Body schema: application/json
email
string <= 128 characters

The email address of the person associated with this Account.

address_1
string <= 64 characters

First line of this Account's billing address.

city
string <= 24 characters

The city for this Account's billing address.

company
string <= 128 characters

The company name associated with this Account.

country
string 2 characters

The two-letter country code of this Account's billing address.

address_2
string <= 64 characters

Second line of this Account's billing address.

first_name
string <= 50 characters

The first name of the person associated with this Account.

last_name
string <= 50 characters

The last name of the person associated with this Account.

phone
string <= 32 characters

The phone number associated with this Account.

state
string <= 24 characters

If billing address is in the United States, this is the State portion of the Account's billing address. If the address is outside the US, this is the Province associated with the Account's billing address.

tax_id
string <= 100 characters

The tax identification number associated with this Account, for tax calculations in some countries. If you do not live in a country that collects tax, this should be null.

zip
string <= 16 characters

The zip code of this Account's billing address.

Responses

200

The updated Account.

Response Schema: application/json
email
string <= 128 characters

The email address of the person associated with this Account.

address_1
string <= 64 characters

First line of this Account's billing address.

balance
number

This Account's balance, in US dollars.

city
string <= 24 characters

The city for this Account's billing address.

credit_card
object

Credit Card information associated with this Account.

company
string <= 128 characters

The company name associated with this Account.

country
string 2 characters

The two-letter country code of this Account's billing address.

address_2
string <= 64 characters

Second line of this Account's billing address.

first_name
string <= 50 characters

The first name of the person associated with this Account.

last_name
string <= 50 characters

The last name of the person associated with this Account.

phone
string <= 32 characters

The phone number associated with this Account.

state
string <= 24 characters

If billing address is in the United States, this is the State portion of the Account's billing address. If the address is outside the US, this is the Province associated with the Account's billing address.

tax_id
string <= 100 characters

The tax identification number associated with this Account, for tax calculations in some countries. If you do not live in a country that collects tax, this should be null.

zip
string <= 16 characters

The zip code of this Account's billing address.

default

Error

Request samples

application/json
Copy
Collapse all Expand all
{
  • "address_1": "123 Main Street",
  • "address_2": "Suite A",
  • "city": "Philadelphia",
  • "company": "Linode LLC",
  • "country": "US",
  • "email": "john.smith@linode.com",
  • "first_name": "John",
  • "last_name": "Smith",
  • "phone": "215-555-1212",
  • "state": "Pennsylvania",
  • "tax_id": "ATU99999999",
  • "zip": 19102
}

Response samples

application/json
Copy
Collapse all Expand all
{
  • "address_1": "123 Main Street",
  • "address_2": "Suite A",
  • "balance": 200,
  • "city": "Philadelphia",
  • "credit_card":
    {
    • "last_four": 1111,
    • "expiry": "11/2022"
    },
  • "company": "Linode LLC",
  • "country": "US",
  • "email": "john.smith@linode.com",
  • "first_name": "John",
  • "last_name": "Smith",
  • "phone": "215-555-1212",
  • "state": "Pennsylvania",
  • "tax_id": "ATU99999999",
  • "zip": 19102
}

Add/Edit Credit Card

post /account/credit-card
https://api.linode.com/v4/account/credit-card

Adds/edit credit card information to your Account. Only one credit card can be associated with your Account, so using this endpoint will overwrite your currently active card information with the new credit card.

Authorizations:
oauth (account:read_write)
Request Body schema: application/json
card_number
required
string <PAN> [ 13 .. 23 ] characters

Your credit card number. No spaces or dashes allowed.

expiry_month
required
integer

A value from 1-12 representing the expiration month of your credit card.

  • 1 = January
  • 2 = February
  • 3 = March
  • Etc.
expiry_year
required
integer

A four-digit integer representing the expiration year of your credit card. The combination of expiry_month and expiry_year must result in a month/year combination of the current month or in the future. An expiration date set in the past is invalid.

Responses

200

Credit Card updated.

Response Schema: application/json
default

Error

Request samples

application/json
Copy
Collapse all Expand all
{
  • "card_number": 4111111111111111,
  • "expiry_month": 12,
  • "expiry_year": 2020
}

Response samples

application/json
Copy
Collapse all Expand all
{ }

List Events

get /account/events
https://api.linode.com/v4/account/events

Returns a collection of Event objects representing actions taken on your Account. The Events returned depends on your grants.

Authorizations:
oauth (events:read_only)
query Parameters
page
integer >= 1
Default: 1

The page of a collection to return.

page_size
integer [ 25 .. 100 ]
Default: 100

The number of items to return per page.

Responses

200

Returns a paginated lists of Event objects.

Response Schema: application/json
data
Array of object
page
integer
pages
integer
results
integer
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/events

Response samples

application/json
Copy
Collapse all Expand all
{
  • "data":
    [
    • {
      • "id": 123,
      • "action": "ticket_create",
      • "created": "2018-01-01T00:01:01",
      • "entity":
        {
        • "id": 11111,
        • "label": "Problem booting my Linode",
        • "type": "ticket",
        • "url": "/v4/support/tickets/11111"
        },
      • "percent_complete": null,
      • "rate": null,
      • "read": true,
      • "seen": true,
      • "status": "failed",
      • "time_remaining": null,
      • "username": "exampleUser"
      }
    ],
  • "page": 1,
  • "pages": 1,
  • "results": 1
}

View Event

get /account/events/{eventId}
https://api.linode.com/v4/account/events/{eventId}

Returns a single Event object.

Authorizations:
oauth (events:read_only)
path Parameters
eventId
required
integer

The ID of the Event.

Responses

200

An Event object

Response Schema: application/json
rate
string

The rate of completion of the Event. Only some Events will return rate; for example, migration and resize Events.

id
integer

The unique ID of this Event.

created
string <date-time>

When this Event was created.

entity
object

Detailed information about the Event's entity, including ID, type, label, and URL used to access it.

percent_complete
integer

A percentage estimating the amount of time remaining for an Event. Returns null for notification events.

action
string
Enum:"backups_enable" "backups_cancel" "backups_restore" "community_question_reply" "credit_card_updated" "disk_create" "disk_delete" "disk_duplicate" "disk_imagize" "disk_resize" "dns_record_create" "dns_record_delete" "dns_zone_create" "dns_zone_delete" "image_delete" "linode_addip" "linode_boot" "linode_clone" "linode_create" "linode_delete" "linode_deleteip" "linode_migrate" "linode_mutate" "linode_reboot" "linode_rebuild" "linode_resize" "linode_shutdown" "linode_snapshot" "longviewclient_create" "longviewclient_delete" "managed_disabled" "managed_enabled" "managed_service_create" "managed_service_delete" "nodebalancer_create" "nodebalancer_delete" "nodebalancer_config_create" "nodebalancer_config_delete" "password_reset" "payment_submitted" "stackscript_create" "stackscript_delete" "stackscript_publicize" "stackscript_revise" "tfa_disabled" "tfa_enabled" "ticket_attachment_upload" "ticket_create" "ticket_update" "volume_attach" "volume_clone" "volume_create" "volume_delete" "volume_detach" "volume_resize"

The action that caused this Event. New actions may be added in the future.

read
boolean

If this Event has been read.

seen
boolean

If this Event has been seen.

status
string
Enum:"failed" "finished" "notification" "scheduled" "started"

The current status of this Event.

time_remaining
string Nullable

The estimated time remaining until the completion of this Event. This value is only returned for some in-progress migration events. For all other in-progress events, the percent_complete attribute will indicate about how much more work is to be done.

username
string

The username of the User who caused the Event.

default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/events/123

Response samples

application/json
Copy
Collapse all Expand all
{
  • "id": 123,
  • "action": "ticket_create",
  • "created": "2018-01-01T00:01:01",
  • "entity":
    {
    • "id": 11111,
    • "label": "Problem booting my Linode",
    • "type": "ticket",
    • "url": "/v4/support/tickets/11111"
    },
  • "percent_complete": null,
  • "rate": null,
  • "read": true,
  • "seen": true,
  • "status": "failed",
  • "time_remaining": null,
  • "username": "exampleUser"
}

Mark Event as Read

post /account/events/{eventId}/read
https://api.linode.com/v4/account/events/{eventId}/read

Marks a single Event as read.

Authorizations:
oauth (events:read_write)
path Parameters
eventId
required
integer

The ID of the Event to designate as read.

Responses

200

Event read.

Response Schema: application/json
default

Error

Request samples

Copy
curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST \
    https://api.linode.com/v4/account/events/123/read

Response samples

application/json
Copy
Collapse all Expand all
{ }

Mark Event as Seen

post /account/events/{eventId}/seen
https://api.linode.com/v4/account/events/{eventId}/seen

Marks all Events up to and including this Event by ID as seen.

Authorizations:
oauth (events:read_only)
path Parameters
eventId
required
integer

The ID of the Event to designate as seen.

Responses

200

Events seen.

Response Schema: application/json
default

Error

Request samples

Copy
curl -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -X POST \
    https://api.linode.com/v4/account/events/123/seen

Response samples

application/json
Copy
Collapse all Expand all
{ }

List Invoices

get /account/invoices
https://api.linode.com/v4/account/invoices

Returns a paginated list of Invoices against your Account.

Authorizations:
oauth (account:read_only)
query Parameters
page
integer >= 1
Default: 1

The page of a collection to return.

page_size
integer [ 25 .. 100 ]
Default: 100

The number of items to return per page.

Responses

200

Returns a paginated list of Invoice objects.

Response Schema: application/json
data
Array of object
page
integer
pages
integer
results
integer
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/invoices

Response samples

application/json
Copy
Collapse all Expand all
{
  • "data":
    [
    • {
      • "id": 123,
      • "date": "2018-01-01T00:01:01",
      • "label": "Invoice",
      • "total": 120
      }
    ],
  • "page": 1,
  • "pages": 1,
  • "results": 1
}

View Invoice

get /account/invoices/{invoiceId}
https://api.linode.com/v4/account/invoices/{invoiceId}

Returns a single Invoice object.

Authorizations:
oauth (account:read_only)
path Parameters
invoiceId
required
integer

The ID of the Invoice.

Responses

200

An Invoice object

Response Schema: application/json
id
integer

The Invoice's unique ID.

date
string <date-time>

When this Invoice was generated.

label
string

The Invoice's display label.

total
integer

The amount of the Invoice in US Dollars.

default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/invoices/123

Response samples

application/json
Copy
Collapse all Expand all
{
  • "id": 123,
  • "date": "2018-01-01T00:01:01",
  • "label": "Invoice",
  • "total": 120
}

List Invoice Items

get /account/invoices/{invoiceId}/items
https://api.linode.com/v4/account/invoices/{invoiceId}/items

Returns a paginated list of Invoice items.

Authorizations:
oauth (account:read_only)
path Parameters
invoiceId
required
integer

The ID of the Invoice.

query Parameters
page
integer >= 1
Default: 1

The page of a collection to return.

page_size
integer [ 25 .. 100 ]
Default: 100

The number of items to return per page.

Responses

200

A paginated list of InvoiceItem objects

Response Schema: application/json
data
Array of object
page
integer
pages
integer
results
integer
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/invoices/123/items

Response samples

application/json
Copy
Collapse all Expand all
{
  • "data":
    [
    • {
      • "amount": 20,
      • "from": "2018-01-01T00:01:01",
      • "label": "Linode 123",
      • "quantity": 1,
      • "to": "2018-01-31T11:59:59",
      • "type": "hourly",
      • "unitprice": 10
      }
    ],
  • "page": 1,
  • "pages": 1,
  • "results": 1
}

List Notifications

get /account/notifications
https://api.linode.com/v4/account/notifications

Returns a collection of Notification objects representing important, often time-sensitive items related to your Account. You cannot interact directly with Notifications, and a Notification will disappear when the circumstances causing it have been resolved. For example, if you have an important Ticket open, you must respond to the Ticket to dismiss the Notification.

Authorizations:
oauth (account:read_only)

Responses

200

Returns a paginated list of Notification objects.

Response Schema: application/json
data
Array of object
page
integer
pages
integer
results
integer
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/notifications

Response samples

application/json
Copy
Collapse all Expand all
{
  • "data":
    [
    • {
      • "entity":
        {
        • "id": 3456,
        • "label": "Linode not booting.",
        • "type": "ticket",
        • "url": "/support/tickets/3456"
        },
      • "label": "You have an important ticket open!",
      • "message": "You have an important ticket open!",
      • "type": "ticket_important",
      • "severity": "major",
      • "when": null,
      • "until": null
      }
    ],
  • "page": 1,
  • "pages": 1,
  • "results": 1
}

List OAuth Clients

get /account/oauth-clients
https://api.linode.com/v4/account/oauth-clients

Returns a paginated list of OAuth Clients registered to your Account. OAuth Clients allow users to log into applications you write or host using their Linode Account, and may allow them to grant some level of access to their Linodes or other entities to your application.

Authorizations:
oauth (account:read_only)
query Parameters
page
integer >= 1
Default: 1

The page of a collection to return.

page_size
integer [ 25 .. 100 ]
Default: 100

The number of items to return per page.

Responses

200

A paginated list of OAuth Clients.

Response Schema: application/json
data
Array of object
page
integer
pages
integer
results
integer
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/oauth-clients

Response samples

application/json
Copy
Collapse all Expand all
{}

Create OAuth Client

post /account/oauth-clients
https://api.linode.com/v4/account/oauth-clients

Creates an OAuth Client, which can be used to allow users (using their Linode account) to log in to your own application, and optionally grant your application some amount of access to their Linodes or other entities.

Authorizations:
oauth (account:read_write)
Request Body schema: application/json
label
required
filterable
string [ 1 .. 512 ] characters

The name of this application. This will be presented to users when they are asked to grant it access to their Account.

redirect_uri
required
string <url>

The location a successful log in from https://login.linode.com should be redirected to for this client. The receiver of this redirect should be ready to accept an OAuth exchange code and finish the OAuth exchange.

Responses

200

Client created successfully.

Response Schema: application/json
id
string

The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).

redirect_uri
string <url>

The location a successful log in from https://login.linode.com should be redirected to for this client. The receiver of this redirect should be ready to accept an OAuth exchange code and finish the OAuth exchange.

label
filterable
string [ 1 .. 512 ] characters

The name of this application. This will be presented to users when they are asked to grant it access to their Account.

status
string
Enum:"active" "disabled" "suspended"

The status of this application. active by default.

secret
string

The OAuth Client secret, used in the OAuth exchange. This is returned as <REDACTED> except when an OAuth Client is created or its secret is reset. This is a secret, and should not be shared or disclosed publicly.

thumbnail_url
string <url> Nullable

The URL where this client's thumbnail may be viewed, or null if this client does not have a thumbnail set.

public
filterable
boolean

If this is a public or private OAuth Client. Public clients have a slightly different authentication workflow than private clients. See the OAuth spec for more details.

default

Error

Request samples

application/json
Copy
Collapse all Expand all
{}

Response samples

application/json
Copy
Collapse all Expand all
{}

View OAuth Client

get /account/oauth-clients/{clientId}
https://api.linode.com/v4/account/oauth-clients/{clientId}

Returns information about a single OAuth client.

Authorizations:
oauth (account:read_only)
path Parameters
clientId
required
string

The OAuth Client ID to look up.

Responses

200

Information about the requested client.

Response Schema: application/json
id
string

The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).

redirect_uri
string <url>

The location a successful log in from https://login.linode.com should be redirected to for this client. The receiver of this redirect should be ready to accept an OAuth exchange code and finish the OAuth exchange.

label
filterable
string [ 1 .. 512 ] characters

The name of this application. This will be presented to users when they are asked to grant it access to their Account.

status
string
Enum:"active" "disabled" "suspended"

The status of this application. active by default.

secret
string

The OAuth Client secret, used in the OAuth exchange. This is returned as <REDACTED> except when an OAuth Client is created or its secret is reset. This is a secret, and should not be shared or disclosed publicly.

thumbnail_url
string <url> Nullable

The URL where this client's thumbnail may be viewed, or null if this client does not have a thumbnail set.

public
filterable
boolean

If this is a public or private OAuth Client. Public clients have a slightly different authentication workflow than private clients. See the OAuth spec for more details.

default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c

Response samples

application/json
Copy
Collapse all Expand all
{}

Update OAuth Client

put /account/oauth-clients/{clientId}
https://api.linode.com/v4/account/oauth-clients/{clientId}

Update information about an OAuth Client on your Account. This can be especially useful to update the redirect_uri of your client in the event that the callback url changed in your application.

Authorizations:
oauth (account:read_write)
path Parameters
clientId
required
string

The OAuth Client ID to look up.

Request Body schema: application/json
redirect_uri
string <url>

The location a successful log in from https://login.linode.com should be redirected to for this client. The receiver of this redirect should be ready to accept an OAuth exchange code and finish the OAuth exchange.

label
filterable
string [ 1 .. 512 ] characters

The name of this application. This will be presented to users when they are asked to grant it access to their Account.

Responses

200

Client updated successfully.

Response Schema: application/json
id
string

The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).

redirect_uri
string <url>

The location a successful log in from https://login.linode.com should be redirected to for this client. The receiver of this redirect should be ready to accept an OAuth exchange code and finish the OAuth exchange.

label
filterable
string [ 1 .. 512 ] characters

The name of this application. This will be presented to users when they are asked to grant it access to their Account.

status
string
Enum:"active" "disabled" "suspended"

The status of this application. active by default.

secret
string

The OAuth Client secret, used in the OAuth exchange. This is returned as <REDACTED> except when an OAuth Client is created or its secret is reset. This is a secret, and should not be shared or disclosed publicly.

thumbnail_url
string <url> Nullable

The URL where this client's thumbnail may be viewed, or null if this client does not have a thumbnail set.

public
filterable
boolean

If this is a public or private OAuth Client. Public clients have a slightly different authentication workflow than private clients. See the OAuth spec for more details.

default

Error

Request samples

application/json
Copy
Collapse all Expand all
{}

Response samples

application/json
Copy
Collapse all Expand all
{}

Delete OAuth Client

delete /account/oauth-clients/{clientId}
https://api.linode.com/v4/account/oauth-clients/{clientId}

Deletes an OAuth Client registered with Linode. The Client ID and Client secret will no longer be accepted by https://login.linode.com, and all tokens issued to this client will be invalidated (meaning that if your application was using a token, it will no longer work).

Authorizations:
oauth (account:read_write)
path Parameters
clientId
required
string

The OAuth Client ID to look up.

Responses

200

Client deleted successfully.

Response Schema: application/json
default

Error

Request samples

Copy
curl -H "Authorization: Bearer $TOKEN" \
    -X DELETE \
    https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c

Response samples

application/json
Copy
Collapse all Expand all
{ }

Reset OAuth Client Secret

post /account/oauth-clients/{clientId}/reset-secret
https://api.linode.com/v4/account/oauth-clients/{clientId}/reset-secret

Resets the OAuth Client secret for a client you own, and returns the OAuth Client with the plaintext secret. This secret is not supposed to be publicly known or disclosed anywhere. This can