Account
v4.83.1 Account View GET
https://api.linode.com/v4/account
Returns the contact and billing information related to your Account.
Authorizations personalAccessToken oauth account:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
default
{
"active_promotions" : [
{
"credit_monthly_cap" : "10.00" ,
"credit_remaining" : "50.00" ,
"description" : "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends." ,
"expire_dt" : "2018-01-31T23:59:59" ,
"image_url" : "https://linode.com/10_a_month_promotion.svg" ,
"summary" : "$10 off your Linode a month!" ,
"this_month_credit_remaining" : "10.00"
}
],
"active_since" : "2018-01-01T00:01:01" ,
"address_1" : "123 Main Street" ,
"address_2" : "Suite A" ,
"balance" : 200 ,
"balance_uninvoiced" : 145 ,
"capabilities" : [
"Linodes" ,
"NodeBalancers" ,
"Block Storage" ,
"Object Storage"
],
"city" : "Philadelphia" ,
"company" : "Linode LLC" ,
"country" : "US" ,
"credit_card" : {
"expiry" : "11/2022" ,
"last_four" : 1111
},
"email" : "john.smith@linode.com" ,
"euuid" : "E1AF5EEC-526F-487D-B317EBEB34C87D71" ,
"first_name" : "John" ,
"last_name" : "Smith" ,
"phone" : "215-555-1212" ,
"state" : "Pennsylvania" ,
"tax_id" : "ATU99999999" ,
"zip" : 19102
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a single Account object.
array of objects
string
The amount available to spend per month.
string
The total amount of credit left for this promotion.
string
A detailed description of this promotion.
string
When this promotion’s credits expire.
string
The location of an image for this promotion.
string
Short details of this promotion.
this_month_credit_remaining
string
The amount of credit left for this month for this promotion.
string <date-time>
The datetime of when the account was activated.
string
<= 64
characters
First line of this Account’s billing address.
string
<= 64
characters
Second line of this Account’s billing address.
number
This Account’s balance, in US dollars.
number
This Account’s current estimated invoice in US dollars. This is not your final invoice balance. Bandwidth charges are not included in the estimate.
array of strings
A list of capabilities your account supports.
string
<= 24
characters
The city for this Account’s billing address.
string
<= 128
characters
The company name associated with this Account.
string
2..2
characters
The two-letter country code of this Account’s billing address.
object
Credit Card information associated with this Account.
string
The expiration month and year of the credit card.
string
The last four digits of the credit card associated with this Account.
string
<= 128
characters
The email address of the person associated with this Account.
string <uuid>
An external unique identifier for this account.
string
<= 50
characters
The first name of the person associated with this Account.
string
<= 50
characters
The last name of the person associated with this Account.
string
<= 32
characters
The phone number associated with this Account.
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.
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.
string
<= 16
characters
The zip code of this Account’s billing address.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Account Update PUT
https://api.linode.com/v4/account
Updates contact and billing information related to your Account.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema array of objects
string
The amount available to spend per month.
string
The total amount of credit left for this promotion.
string
A detailed description of this promotion.
string
When this promotion’s credits expire.
string
The location of an image for this promotion.
string
Short details of this promotion.
this_month_credit_remaining
string
The amount of credit left for this month for this promotion.
string
<= 64
characters
First line of this Account’s billing address.
string
<= 64
characters
Second line of this Account’s billing address.
string
<= 24
characters
The city for this Account’s billing address.
string
<= 128
characters
The company name associated with this Account.
string
2..2
characters
The two-letter country code of this Account’s billing address.
string
<= 128
characters
The email address of the person associated with this Account.
string
<= 50
characters
The first name of the person associated with this Account.
string
<= 50
characters
The last name of the person associated with this Account.
string
<= 32
characters
The phone number associated with this Account.
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.
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.
string
<= 16
characters
The zip code of this Account’s billing address.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"address_1": "123 Main St.",
"address_2": "Suite 101",
"city": "Philadelphia",
"company": "My Company, LLC",
"country": "US",
"email": "jsmith@mycompany.com",
"first_name": "John",
"last_name": "Smith",
"phone": "555-555-1212",
"state": "PA",
"zip": 19102,
}
}' \
linode-cli account update \
\
Response Samples
200
default
{
"active_promotions" : [
{
"credit_monthly_cap" : "10.00" ,
"credit_remaining" : "50.00" ,
"description" : "Receive up to $10 off your services every month for 6 months! Unused credits will expire once this promotion period ends." ,
"expire_dt" : "2018-01-31T23:59:59" ,
"image_url" : "https://linode.com/10_a_month_promotion.svg" ,
"summary" : "$10 off your Linode a month!" ,
"this_month_credit_remaining" : "10.00"
}
],
"active_since" : "2018-01-01T00:01:01" ,
"address_1" : "123 Main Street" ,
"address_2" : "Suite A" ,
"balance" : 200 ,
"balance_uninvoiced" : 145 ,
"capabilities" : [
"Linodes" ,
"NodeBalancers" ,
"Block Storage" ,
"Object Storage"
],
"city" : "Philadelphia" ,
"company" : "Linode LLC" ,
"country" : "US" ,
"credit_card" : {
"expiry" : "11/2022" ,
"last_four" : 1111
},
"email" : "john.smith@linode.com" ,
"euuid" : "E1AF5EEC-526F-487D-B317EBEB34C87D71" ,
"first_name" : "John" ,
"last_name" : "Smith" ,
"phone" : "215-555-1212" ,
"state" : "Pennsylvania" ,
"tax_id" : "ATU99999999" ,
"zip" : 19102
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The updated Account.
array of objects
string
The amount available to spend per month.
string
The total amount of credit left for this promotion.
string
A detailed description of this promotion.
string
When this promotion’s credits expire.
string
The location of an image for this promotion.
string
Short details of this promotion.
this_month_credit_remaining
string
The amount of credit left for this month for this promotion.
string <date-time>
The datetime of when the account was activated.
string
<= 64
characters
First line of this Account’s billing address.
string
<= 64
characters
Second line of this Account’s billing address.
number
This Account’s balance, in US dollars.
number
This Account’s current estimated invoice in US dollars. This is not your final invoice balance. Bandwidth charges are not included in the estimate.
array of strings
A list of capabilities your account supports.
string
<= 24
characters
The city for this Account’s billing address.
string
<= 128
characters
The company name associated with this Account.
string
2..2
characters
The two-letter country code of this Account’s billing address.
object
Credit Card information associated with this Account.
string
The expiration month and year of the credit card.
string
The last four digits of the credit card associated with this Account.
string
<= 128
characters
The email address of the person associated with this Account.
string <uuid>
An external unique identifier for this account.
string
<= 50
characters
The first name of the person associated with this Account.
string
<= 50
characters
The last name of the person associated with this Account.
string
<= 32
characters
The phone number associated with this Account.
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.
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.
string
<= 16
characters
The zip code of this Account’s billing address.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Account Cancel POST
https://api.linode.com/v4/account/cancel
Cancels an active Linode account. This action will cause Linode to attempt to charge the credit card on file for the remaining balance. An error will occur if Linode fails to charge the credit card on file. Restricted users will not be able to cancel an account.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema string
Any reason for cancelling the account, and any other comments you might have about your Linode service.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"comments": "I' m consolidating my accounts."
}
}' \
https://api.linode.com/v4/account/cancel
linode-cli account cancel \
"I'm consolidating my accounts"
Response Samples
200
409
default
{
"survey_link" : "https://alinktothesurvey.com"
}
{
"errors" : [
{
"reason" : "We were unable to charge your credit card for services rendered. We cannot cancel this account until the balance has been paid.\n"
}
]
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
409
default
Account cancelled
string
A link to Linode’s exit survey.
Could not charge the credit card on file
array of objects
string
A string explaining that the account could not be cancelled because there is an outstanding balance on the account that must be paid first.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Credit Card Add/Edit POST
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 personalAccessToken oauth account:read_write
Request Body Schema string
13..23
characters
Your credit card number. No spaces or dashes allowed.
string
The Card Verification Value on the back of the card.
integer
A value from 1-12 representing the expiration month of your credit card.
1 = January 2 = February 3 = March Etc. 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.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"card_number": "4111111111111111",
"expiry_month": 11,
"expiry_year": 2020,
"cvv": "111"
}' \
linode-cli account update-card \
4111111111111111 \
11 \
2025 \
111
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Events List GET
https://api.linode.com/v4/account/events
Returns a collection of Event objects representing actions taken on your Account from the last 90 days. The Events returned depend on your grants.
Authorizations personalAccessToken oauth events:read_only
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
default
{
"data" : [
{
"action" : "ticket_create" ,
"created" : "2018-01-01T00:01:01" ,
"duration" : 300.56 ,
"entity" : {
"id" : 11111 ,
"label" : "Problem booting my Linode" ,
"type" : "ticket" ,
"url" : "/v4/support/tickets/11111"
},
"id" : 123 ,
"message" : "None" ,
"percent_complete" : null ,
"rate" : null ,
"read" : true ,
"secondary_entity" : {
"id" : "linode/debian9" ,
"label" : "linode1234" ,
"type" : "linode" ,
"url" : "/v4/linode/instances/1234"
},
"seen" : true ,
"status" : null ,
"time_remaining" : null ,
"username" : "exampleUser"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a paginated lists of Event objects from the last 90 days.
array of objects
stringEnum:
account_update
account_settings_update
backups_enable
backups_cancel
backups_restore
community_question_reply
community_like
credit_card_updated
disk_create
disk_delete
disk_update
disk_duplicate
disk_imagize
disk_resize
dns_record_create
dns_record_delete
dns_record_update
dns_zone_create
dns_zone_delete
dns_zone_import
dns_zone_update
firewall_create
firewall_delete
firewall_disable
firewall_enable
firewall_update
firewall_device_add
firewall_device_remove
host_reboot
image_delete
image_update
ipaddress_update
lassie_reboot
lish_boot
linode_addip
linode_boot
linode_clone
linode_create
linode_delete
linode_update
linode_deleteip
linode_migrate
linode_migrate_datacenter
linode_migrate_datacenter_create
linode_mutate
linode_mutate_create
linode_reboot
linode_rebuild
linode_resize
linode_resize_create
linode_shutdown
linode_snapshot
linode_config_create
linode_config_delete
linode_config_update
lke_node_create
longviewclient_create
longviewclient_delete
longviewclient_update
managed_disabled
managed_enabled
managed_service_create
managed_service_delete
nodebalancer_create
nodebalancer_delete
nodebalancer_update
nodebalancer_config_create
nodebalancer_config_delete
nodebalancer_config_update
nodebalancer_node_create
nodebalancer_node_delete
nodebalancer_node_update
oauth_client_create
oauth_client_delete
oauth_client_secret_reset
oauth_client_update
password_reset
payment_submitted
profile_update
stackscript_create
stackscript_delete
stackscript_update
stackscript_publicize
stackscript_revise
tag_create
tag_delete
tfa_disabled
tfa_enabled
ticket_attachment_upload
ticket_create
ticket_update
token_create
token_delete
token_update
user_create
user_update
user_delete
user_ssh_key_add
user_ssh_key_delete
user_ssh_key_update
vlan_attach
vlan_detach
volume_attach
volume_clone
volume_create
volume_delete
volume_update
volume_detach
volume_resize
The action that caused this Event. New actions may be added in the future.
string <date-time>
When this Event was created.
number
The total duration in seconds that it takes for the Event to complete.
object
Detailed information about the Event’s entity, including ID, type, label, and URL used to access it.
integer
The unique ID for an Event’s entity.
Some Event entities do not have IDs associated with them, so they
will not be returned when filtering by ID. These Events include:
Entities for some Events are assigned the ID of the Linode they correspond to.
When filtering by ID for these Events, use the corresponding Linode’s ID.
These Events include:
Tag Events use a tag’s name for the entity ID field. When filtering by ID
for tag Events, supply the name of the tag.
string
The current label of this object. The label may reflect changes that occur with this Event.
stringEnum:
account
backups
community
disks
domain
firewall
image
ipaddress
linode
longview
managed_service
nodebalancer
oauth_client
profile
stackscript
tag
ticket
token
user
user_ssh_key
volume
The type of entity that is being referenced by the Event.
string
The URL where you can access the object this Event is for. If a relative URL, it is relative to the domain you retrieved the Event from.
integer
The unique ID of this Event.
string
Provides additional information about the event. Additional information may include, but is not limited to, a more detailed representation of events which can help diagnose non-obvious failures.
integer
A percentage estimating the amount of time remaining for an Event.
Returns null for notification events.
string
The rate of completion of the Event. Only some Events will return rate; for example, migration and resize Events.
boolean
If this Event has been read.
object
Detailed information about the Event’s secondary entity, which provides additional information
for events such as, but not limited to, linode_boot, linode_reboot, linode_create, and linode_clone Event actions.
string
The ID of the object that is the secondary entity.
string
The label of this object.
string
The type of entity that is being referenced by the Event.
string
The URL where you can access the object this Event is for. If a relative URL, it is relative to the domain you retrieved the Event from.
boolean
If this Event has been seen.
stringEnum:
failed
finished
notification
scheduled
started
The current status of this Event.
string
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.
string
The username of the User who caused the Event.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Event View GET
https://api.linode.com/v4/account/events/{eventId}
Returns a single Event object.
Authorizations personalAccessToken oauth events:read_only
Path Parameters eventId integer
Required The ID of the Event.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli events view 123
Response Samples
200
default
{
"action" : "ticket_create" ,
"created" : "2018-01-01T00:01:01" ,
"duration" : 300.56 ,
"entity" : {
"id" : 11111 ,
"label" : "Problem booting my Linode" ,
"type" : "ticket" ,
"url" : "/v4/support/tickets/11111"
},
"id" : 123 ,
"message" : "None" ,
"percent_complete" : null ,
"rate" : null ,
"read" : true ,
"secondary_entity" : {
"id" : "linode/debian9" ,
"label" : "linode1234" ,
"type" : "linode" ,
"url" : "/v4/linode/instances/1234"
},
"seen" : true ,
"status" : null ,
"time_remaining" : null ,
"username" : "exampleUser"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
An Event object
stringEnum:
account_update
account_settings_update
backups_enable
backups_cancel
backups_restore
community_question_reply
community_like
credit_card_updated
disk_create
disk_delete
disk_update
disk_duplicate
disk_imagize
disk_resize
dns_record_create
dns_record_delete
dns_record_update
dns_zone_create
dns_zone_delete
dns_zone_import
dns_zone_update
firewall_create
firewall_delete
firewall_disable
firewall_enable
firewall_update
firewall_device_add
firewall_device_remove
host_reboot
image_delete
image_update
ipaddress_update
lassie_reboot
lish_boot
linode_addip
linode_boot
linode_clone
linode_create
linode_delete
linode_update
linode_deleteip
linode_migrate
linode_migrate_datacenter
linode_migrate_datacenter_create
linode_mutate
linode_mutate_create
linode_reboot
linode_rebuild
linode_resize
linode_resize_create
linode_shutdown
linode_snapshot
linode_config_create
linode_config_delete
linode_config_update
lke_node_create
longviewclient_create
longviewclient_delete
longviewclient_update
managed_disabled
managed_enabled
managed_service_create
managed_service_delete
nodebalancer_create
nodebalancer_delete
nodebalancer_update
nodebalancer_config_create
nodebalancer_config_delete
nodebalancer_config_update
nodebalancer_node_create
nodebalancer_node_delete
nodebalancer_node_update
oauth_client_create
oauth_client_delete
oauth_client_secret_reset
oauth_client_update
password_reset
payment_submitted
profile_update
stackscript_create
stackscript_delete
stackscript_update
stackscript_publicize
stackscript_revise
tag_create
tag_delete
tfa_disabled
tfa_enabled
ticket_attachment_upload
ticket_create
ticket_update
token_create
token_delete
token_update
user_create
user_update
user_delete
user_ssh_key_add
user_ssh_key_delete
user_ssh_key_update
vlan_attach
vlan_detach
volume_attach
volume_clone
volume_create
volume_delete
volume_update
volume_detach
volume_resize
The action that caused this Event. New actions may be added in the future.
string <date-time>
When this Event was created.
number
The total duration in seconds that it takes for the Event to complete.
object
Detailed information about the Event’s entity, including ID, type, label, and URL used to access it.
integer
The unique ID for an Event’s entity.
Some Event entities do not have IDs associated with them, so they
will not be returned when filtering by ID. These Events include:
Entities for some Events are assigned the ID of the Linode they correspond to.
When filtering by ID for these Events, use the corresponding Linode’s ID.
These Events include:
Tag Events use a tag’s name for the entity ID field. When filtering by ID
for tag Events, supply the name of the tag.
string
The current label of this object. The label may reflect changes that occur with this Event.
stringEnum:
account
backups
community
disks
domain
firewall
image
ipaddress
linode
longview
managed_service
nodebalancer
oauth_client
profile
stackscript
tag
ticket
token
user
user_ssh_key
volume
The type of entity that is being referenced by the Event.
string
The URL where you can access the object this Event is for. If a relative URL, it is relative to the domain you retrieved the Event from.
integer
The unique ID of this Event.
string
Provides additional information about the event. Additional information may include, but is not limited to, a more detailed representation of events which can help diagnose non-obvious failures.
integer
A percentage estimating the amount of time remaining for an Event.
Returns null for notification events.
string
The rate of completion of the Event. Only some Events will return rate; for example, migration and resize Events.
boolean
If this Event has been read.
object
Detailed information about the Event’s secondary entity, which provides additional information
for events such as, but not limited to, linode_boot, linode_reboot, linode_create, and linode_clone Event actions.
string
The ID of the object that is the secondary entity.
string
The label of this object.
string
The type of entity that is being referenced by the Event.
string
The URL where you can access the object this Event is for. If a relative URL, it is relative to the domain you retrieved the Event from.
boolean
If this Event has been seen.
stringEnum:
failed
finished
notification
scheduled
started
The current status of this Event.
string
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.
string
The username of the User who caused the Event.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Event Mark as Read POST
https://api.linode.com/v4/account/events/{eventId}/read
Marks a single Event as read.
Authorizations personalAccessToken oauth events:read_only
Path Parameters eventId integer
Required The ID of the Event to designate as read.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
\
linode-cli events mark-read 123
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Event Mark as Seen POST
https://api.linode.com/v4/account/events/{eventId}/seen
Marks all Events up to and including this Event by ID as seen.
Authorizations personalAccessToken oauth events:read_only
Path Parameters eventId integer
Required The ID of the Event to designate as seen.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
\
linode-cli events mark-seen 123
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Invoices List GET
https://api.linode.com/v4/account/invoices
Returns a paginated list of Invoices against your Account.
Authorizations personalAccessToken oauth account:read_only
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account invoices-list
Response Samples
200
default
{
"data" : [
{
"date" : "2018-01-01T00:01:01" ,
"id" : 123 ,
"label" : "Invoice" ,
"subtotal" : 120.25 ,
"tax" : 12.25 ,
"total" : 132.5
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a paginated list of Invoice objects.
array of objects
string <date-time>
When this Invoice was generated.
integer
The Invoice’s unique ID.
string
The Invoice’s display label.
number
The amount of the Invoice before taxes in US Dollars.
number
The amount of tax levied on the Invoice in US Dollars.
number
The amount of the Invoice after taxes in US Dollars.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Invoice View GET
https://api.linode.com/v4/account/invoices/{invoiceId}
Returns a single Invoice object.
Authorizations personalAccessToken oauth account:read_only
Path Parameters invoiceId integer
Required The ID of the Invoice.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account invoice-view 123
Response Samples
200
default
{
"date" : "2018-01-01T00:01:01" ,
"id" : 123 ,
"label" : "Invoice" ,
"subtotal" : 120.25 ,
"tax" : 12.25 ,
"total" : 132.5
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
An Invoice object
string <date-time>
When this Invoice was generated.
integer
The Invoice’s unique ID.
string
The Invoice’s display label.
number
The amount of the Invoice before taxes in US Dollars.
number
The amount of tax levied on the Invoice in US Dollars.
number
The amount of the Invoice after taxes in US Dollars.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Invoice Items List GET
https://api.linode.com/v4/account/invoices/{invoiceId}/items
Returns a paginated list of Invoice items.
Authorizations personalAccessToken oauth account:read_only
Path Parameters invoiceId integer
Required The ID of the Invoice.
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account invoice-items 123
Response Samples
200
default
{
"data" : [
{
"amount" : 20.2 ,
"from" : "2018-01-01T00:01:01" ,
"label" : "Linode 123" ,
"quantity" : 4 ,
"tax" : 1.25 ,
"to" : "2018-01-31T11:59:59" ,
"total" : 21.45 ,
"type" : "hourly" ,
"unit_price" : 5.05
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of InvoiceItem objects
array of objects
number
The price, in US dollars, of the Invoice Item. Equal to the unit price multiplied by quantity.
string <date-time>
The date the Invoice Item started, based on month.
string
The Invoice Item’s display label.
integer
The quantity of this Item for the specified Invoice.
number
The amount of tax levied on this Item in US Dollars.
string <date-time>
The date the Invoice Item ended, based on month.
number
The price of this Item after taxes in US Dollars.
stringEnum:
hourly
misc
The type of service, ether hourly or misc.
string
The monthly service fee in US Dollars for this Item.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User Logins List All GET
https://api.linode.com/v4/account/logins
Returns a collection of successful logins for all users on the account during the last 90 days. This command can only be accessed by the unrestricted users of an account.
Authorizations personalAccessToken oauth account:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account logins-list
Response Samples
200
default
{
"data" : [
{
"datetime" : "2018-01-01T00:01:01" ,
"id" : 1234 ,
"ip" : "192.0.2.0" ,
"restricted" : true ,
"username" : "example_user"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A collection of successful logins for all users on the account during the last 90 days.
array of objects
string <date-time>
When the login was initiated.
integer
The unique ID of this login object.
string <ip>
The remote IP address that requested the login.
boolean
True if the User that was logged into was a restricted User, false otherwise.
string
The username of the User that was logged into.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Login View GET
https://api.linode.com/v4/account/logins/{loginId}
Returns a Login object that displays information about a successful login. The logins that can be viewed can be for any user on the account, and are not limited to only the logins of the user that is accessing this API endpoint. This command can only be accessed by the unrestricted users of the account.
Authorizations personalAccessToken oauth account:read_only
Path Parameters loginId integer
Required The ID of the login object to access.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account login-view 1234
Response Samples
200
default
{
"datetime" : "2018-01-01T00:01:01" ,
"id" : 1234 ,
"ip" : "192.0.2.0" ,
"restricted" : true ,
"username" : "example_user"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The requested login object.
string <date-time>
When the login was initiated.
integer
The unique ID of this login object.
string <ip>
The remote IP address that requested the login.
boolean
True if the User that was logged into was a restricted User, false otherwise.
string
The username of the User that was logged into.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Maintenance List GET
https://api.linode.com/v4beta/account/maintenance
Beta
Returns a collection of Maintenance objects for any entity a user has permissions to view.
Currently, Linodes are the only entities available for viewing.
Beta : This endpoint is in beta. Please make sure to prepend all requests with /v4beta instead of /v4, and be aware that this endpoint may receive breaking updates in the future. This notice will be removed when this endpoint is out of beta.
Authorizations personalAccessToken oauth maintenance:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account maintenance-list
Response Samples
200
default
{
"data" : [
{
"entity" : {
"id" : 1234 ,
"label" : "demo-linode" ,
"type" : "Linode" ,
"url" : "https://api.linode.com/v4/linode/instances/{linodeId}"
},
"reason" : "This maintenance will allow us to update the BIOS on the host’s motherboard." ,
"status" : "started" ,
"type" : "reboot" ,
"when" : "2020-07-09T00:01:01"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a paginated list of Maintenance objects.
array of objects
object
The entity being affected by maintenance.
number
The id of the entity being affected by maintenance.
string
The label of the entity being affected by maintenance.
string
The type of entity.
string
The API endpoint prefix to use in combination with the entity id to find specific information about the entity.
string
The reason maintenance is being performed.
stringEnum:
pending
ready
started
completed
The maintenance status.
stringEnum:
reboot
cold_migration
live_migration
The type of maintenance.
string <date-time>
When the maintenance will begin.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Notifications List GET
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 personalAccessToken oauth account:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account notifications-list
Response Samples
200
default
{
"data" : [
{
"body" : null ,
"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!" ,
"severity" : "major" ,
"type" : "ticket_important" ,
"until" : null ,
"when" : null
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a paginated list of Notification objects.
array of objects
string
A full description of this Notification, in markdown format. Not all Notifications include bodies.
object
Detailed information about the Notification.
integer
The unique ID of the Notification’s entity, based on the entity type.
string
The current label for this Notification’s entity.
string
The type of entity this is related to.
string
The URL where you can access the object this Notification is for. If a relative URL, it is relative to the domain you retrieved the Notification from.
string
A short description of this Notification.
string
A human-readable description of the Notification.
stringEnum:
minor
major
critical
The severity of this Notification. This field can be used to decide how prominently to display the Notification, what color to make the display text, etc.
stringEnum:
migration_scheduled
migration_imminent
migration_pending
reboot_scheduled
outage
payment_due
ticket_important
ticket_abuse
notice
maintenance
promotion
The type of Notification this is.
string <date-time>
If this Notification has a duration, this will be the ending time for the Event/action. For example, if there is scheduled maintenance for one of our systems, until would be set to the end of the maintenance window.
string <date-time>
If this Notification is of an Event that will happen at a fixed, future time, this is when the named action will be taken. For example, if a Linode is to be migrated in response to a Security Advisory, this field will contain the approximate time the Linode will be taken offline for migration.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Clients List GET
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 personalAccessToken oauth account:read_only
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account clients-list
Response Samples
200
default
{
"data" : [
{
"id" : "2737bf16b39ab5d7b4a1" ,
"label" : "Test_Client_1" ,
"public" : false ,
"redirect_uri" : "https://example.org/oauth/callback" ,
"secret" : "\u003cREDACTED\u003e" ,
"status" : "active" ,
"thumbnail_url" : "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of OAuth Clients.
array of objects
string
The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).
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.
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.
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.
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.
stringEnum:
active
disabled
suspended
The status of this application. active by default.
string <url>
The URL where this client’s thumbnail may be viewed, or null if this client does not have a thumbnail set.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Create POST
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 personalAccessToken oauth account:read_write
Request Body Schema 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.
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.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"redirect_uri": "https://example.org/oauth/callback",
"label": "Test_Client_1",
"public": false
}' \
linode-cli account client-create \
\
Response Samples
200
default
{
"id" : "2737bf16b39ab5d7b4a1" ,
"label" : "Test_Client_1" ,
"public" : false ,
"redirect_uri" : "https://example.org/oauth/callback" ,
"secret" : "\u003cREDACTED\u003e" ,
"status" : "active" ,
"thumbnail_url" : "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Client created successfully.
string
The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).
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.
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.
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.
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.
stringEnum:
active
disabled
suspended
The status of this application. active by default.
string <url>
The URL where this client’s thumbnail may be viewed, or null if this client does not have a thumbnail set.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Delete DELETE
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 personalAccessToken oauth account:read_write
Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli account client-delete \
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Client deleted successfully.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client View GET
https://api.linode.com/v4/account/oauth-clients/{clientId}
Returns information about a single OAuth client.
Authorizations personalAccessToken oauth account:read_only
Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account client-view \
Response Samples
200
default
{
"id" : "2737bf16b39ab5d7b4a1" ,
"label" : "Test_Client_1" ,
"public" : false ,
"redirect_uri" : "https://example.org/oauth/callback" ,
"secret" : "\u003cREDACTED\u003e" ,
"status" : "active" ,
"thumbnail_url" : "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Information about the requested client.
string
The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).
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.
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.
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.
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.
stringEnum:
active
disabled
suspended
The status of this application. active by default.
string <url>
The URL where this client’s thumbnail may be viewed, or null if this client does not have a thumbnail set.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Update PUT
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 personalAccessToken oauth account:read_write
Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Body Schema 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.
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.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"redirect_uri": "https://example.org/oauth/callback",
"label": "Test_Client_1"
}
}' \
linode-cli account client-update \
\
Response Samples
200
default
{
"id" : "2737bf16b39ab5d7b4a1" ,
"label" : "Test_Client_1" ,
"public" : false ,
"redirect_uri" : "https://example.org/oauth/callback" ,
"secret" : "\u003cREDACTED\u003e" ,
"status" : "active" ,
"thumbnail_url" : "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Client updated successfully.
string
The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).
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.
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.
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.
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.
stringEnum:
active
disabled
suspended
The status of this application. active by default.
string <url>
The URL where this client’s thumbnail may be viewed, or null if this client does not have a thumbnail set.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Secret Reset POST
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 be used to generate a new secret in case the one you have has been leaked, or to get a new secret if you lost the original. The old secret is expired immediately, and logins to your client with the old secret will fail.
Authorizations personalAccessToken oauth account:read_write
Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
\
linode-cli account client-reset-secret \
Response Samples
200
default
{
"id" : "2737bf16b39ab5d7b4a1" ,
"label" : "Test_Client_1" ,
"public" : false ,
"redirect_uri" : "https://example.org/oauth/callback" ,
"secret" : "\u003cREDACTED\u003e" ,
"status" : "active" ,
"thumbnail_url" : "https://api.linode.com/v4/account/clients/2737bf16b39ab5d7b4a1/thumbnail"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Client secret reset successfully.
string
The OAuth Client ID. This is used to identify the client, and is a publicly-known value (it is not a secret).
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.
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.
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.
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.
stringEnum:
active
disabled
suspended
The status of this application. active by default.
string <url>
The URL where this client’s thumbnail may be viewed, or null if this client does not have a thumbnail set.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Thumbnail View GET
https://api.linode.com/v4/account/oauth-clients/{clientId}/thumbnail
Returns the thumbnail for this OAuth Client. This is a publicly-viewable endpoint, and can be accessed without authentication.
Authorizations Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Samples
Shell
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
OAuth Client Thumbnail Update PUT
https://api.linode.com/v4/account/oauth-clients/{clientId}/thumbnail
Upload a thumbnail for a client you own. You must upload an image file that will be returned when the thumbnail is retrieved. This image will be publicly-viewable.
Authorizations personalAccessToken oauth account:read_write
Path Parameters clientId string
Required The OAuth Client ID to look up.
Request Samples
Shell
curl -H "Content-Type: image/png" \
"Authorization: Bearer $TOKEN " \
\
"/path/to/image"
https://api.linode.com/v4/account/oauth-clients/edc6790ea9db4d224c5c/thumbnail
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Thumbnail updated successfully.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Payments List GET
https://api.linode.com/v4/account/payments
Returns a paginated list of Payments made on this Account.
Authorizations personalAccessToken oauth account:read_only
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account payments-list
Response Samples
200
default
{
"data" : [
{
"date" : "2018-01-15T00:01:01" ,
"id" : 123 ,
"usd" : "120.50"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a paginated list of Payment objects.
array of objects
string <date-time>
When the Payment was made.
integer
The unique ID of the Payment.
integer
The amount, in US dollars, of the Payment.
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Payment Make POST
https://api.linode.com/v4/account/payments
Makes a Payment to your Account via credit card. This will charge your credit card the requested amount.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema string
CVV (Card Verification Value) of the credit card to be used for the Payment.
string
The amount in US Dollars of the Payment. The maximum credit card payment that can be made is $50,000 dollars.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"cvv": "123",
"usd": "120.50"
}' \
linode-cli account payment-create \
123 \
Response Samples
200
default
{
"date" : "2018-01-15T00:01:01" ,
"id" : 123 ,
"usd" : "120.50"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Payment made.
string <date-time>
When the Payment was made.
integer
The unique ID of the Payment.
integer
The amount, in US dollars, of the Payment.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
PayPal Payment Stage POST
https://api.linode.com/v4/account/payments/paypal
This begins the process of submitting a Payment via PayPal. After calling this endpoint, you must take the resulting payment_id along with the payer_id from your PayPal account and
POST /account/payments/paypal-execute to complete the Payment.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema string
The URL to have PayPal redirect to when Payment is cancelled.
string
The URL to have PayPal redirect to when Payment is approved.
string
The payment amount in USD. Minimum accepted value of $5 USD. Maximum accepted value of $500 USD or credit card payment limit; whichever value is highest. PayPal’s maximum transaction limit is $10,000 USD.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"usd": "120.50",
"redirect_url": "https://example.org",
"cancel_url": "https://example.org"
}' \
linode-cli account paypal-start \
\
\
Response Samples
200
default
{
"checkout_token" : "EC-1A2B3C4D5E6F7G8H9" ,
"payment_id" : "PAY-1234567890ABCDEFGHIJKLMN"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
PayPal Payment staged.
string
The checkout token generated for this Payment.
string
The paypal-generated ID for this Payment. Used when authorizing the Payment in PayPal’s interface.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Staged/Approved PayPal Payment Execute POST
https://api.linode.com/v4/account/payments/paypal/execute
Given a PaymentID and PayerID - as generated by PayPal during the transaction authorization process - this endpoint executes the Payment to capture the funds and credit your Linode Account.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema string
The PayerID returned by PayPal during the transaction authorization process.
string
The PaymentID returned from
POST /account/payments/paypal that has been approved with PayPal.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"payment_id": "PAY-1234567890ABCDEFGHIJKLMN",
"payer_id": "ABCDEFGHIJKLM"
}' \
linode-cli account paypal-execute
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Payment View GET
https://api.linode.com/v4/account/payments/{paymentId}
Returns information about a specific Payment.
Authorizations personalAccessToken oauth account:read_only
Path Parameters paymentId integer
Required The ID of the Payment to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account payment-view 123
Response Samples
200
default
{
"date" : "2018-01-15T00:01:01" ,
"id" : 123 ,
"usd" : "120.50"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A Payment object.
string <date-time>
When the Payment was made.
integer
The unique ID of the Payment.
integer
The amount, in US dollars, of the Payment.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Account Settings View GET
https://api.linode.com/v4/account/settings
Returns information related to your Account settings: Managed service subscription, Longview subscription, and network helper.
Authorizations personalAccessToken oauth account:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account settings
Response Samples
200
default
{
"backups_enabled" : true ,
"longview_subscription" : "longview-3" ,
"managed" : true ,
"network_helper" : false ,
"object_storage" : "active"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a single Account settings object.
boolean
Account-wide backups default. If true, all Linodes created will automatically be enrolled in the Backups service. If false, Linodes will not be enrolled by default, but may still be enrolled on creation or later.
string
The Longview Pro tier you are currently subscribed to. The value must be a
Longview Subscription ID or null for Longview Free.
boolean
Our 24/7 incident response service. This robust, multi-homed monitoring system distributes monitoring checks to ensure that your servers remain online and available at all times. Linode Managed can monitor any service or software stack reachable over TCP or HTTP. Once you add a service to Linode Managed, we’ll monitor it for connectivity, response, and total request time.
boolean
Enables network helper across all users by default for new Linodes and Linode Configs.
stringEnum:
disabled
suspended
active
Default:
disabled
A string describing the status of this account’s Object Storage service enrollment.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Account Settings Update PUT
https://api.linode.com/v4/account/settings
Updates your Account settings.
To update your Longview subscription plan, send a request to
Update Longview Plan .
Authorizations personalAccessToken oauth account:read_write
Request Body Schema boolean
Account-wide backups default. If true, all Linodes created will automatically be enrolled in the Backups service. If false, Linodes will not be enrolled by default, but may still be enrolled on creation or later.
boolean
Enables network helper across all users by default for new Linodes and Linode Configs.
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"network_helper": true,
}' \
linode-cli account settings-update \
false
Response Samples
200
default
{
"backups_enabled" : true ,
"longview_subscription" : "longview-3" ,
"managed" : true ,
"network_helper" : false ,
"object_storage" : "active"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The updated Account settings.
boolean
Account-wide backups default. If true, all Linodes created will automatically be enrolled in the Backups service. If false, Linodes will not be enrolled by default, but may still be enrolled on creation or later.
string
The Longview Pro tier you are currently subscribed to. The value must be a
Longview Subscription ID or null for Longview Free.
boolean
Our 24/7 incident response service. This robust, multi-homed monitoring system distributes monitoring checks to ensure that your servers remain online and available at all times. Linode Managed can monitor any service or software stack reachable over TCP or HTTP. Once you add a service to Linode Managed, we’ll monitor it for connectivity, response, and total request time.
boolean
Enables network helper across all users by default for new Linodes and Linode Configs.
stringEnum:
disabled
suspended
active
Default:
disabled
A string describing the status of this account’s Object Storage service enrollment.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Linode Managed Enable POST
https://api.linode.com/v4/account/settings/managed-enable
Enables Linode Managed for the entire account and sends a welcome email to the account’s associated email address. Linode Managed can monitor any service or software stack reachable over TCP or HTTP. See our
Linode Managed guide to learn more.
Authorizations personalAccessToken oauth account:read_write
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli account enable-managed
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Managed services enabled for account.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Network Utilization View GET
https://api.linode.com/v4/account/transfer
Returns a Transfer object showing your network utilization, in GB, for the current month.
Authorizations personalAccessToken oauth account:read_only
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli account transfer
Response Samples
200
default
{
"billable" : 0 ,
"quota" : 9141 ,
"used" : 2
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Returns a single Transfer object.
integer
The amount of your transfer pool that is billable this billing cycle.
integer
The amount of network usage allowed this billing cycle.
integer
The amount of network usage you have used this billing cycle.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
Users List GET
https://api.linode.com/v4/account/users
Returns a paginated list of Users on your Account. Users may access all or part of your Account based on their restricted status and grants. An unrestricted User may access everything on the account, whereas restricted User may only access entities or perform actions they’ve been given specific grants to.
Authorizations personalAccessToken oauth account:read_only
Query Parameters page Type: integer
>= 1Default:
1
Default: 1 The page of a collection to return.
page_size Type: integer
25..100Default:
100
Default: 100 The number of items to return per page.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
default
{
"data" : [
{
"email" : "example_user@linode.com" ,
"restricted" : true ,
"ssh_keys" : [
"home-pc" ,
"laptop"
],
"tfa_enabled" : null ,
"username" : "example_user"
}
],
"page" : 1 ,
"pages" : 1 ,
"results" : 1
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
A paginated list of Users.
array of objects
string <email>
The email address for this User, for account management communications, and may be used for other communications as configured.
boolean
If true, this User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
array of strings
A list of SSH Key labels added by this User. These are the keys that will be deployed if this User is included in the authorized_users field of a
create Linode ,
rebuild Linode , or
create Disk request.
boolean
A boolean value indicating if the User has Two Factor Authentication (TFA) enabled. See the Create Two Factor Secret (
/profile/tfa-enable ) endpoint to enable TFA.
string
3..32
characters
This User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
integer
integer
integer
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User Create POST
https://api.linode.com/v4/account/users
Creates a User on your Account. Once created, the User will be able to log in and access portions of your Account. Access is determined by whether or not they are restricted, and what grants they have been given.
Authorizations personalAccessToken oauth account:read_write
Request Body Schema string <email>
The new User’s email address.
boolean
If true, the new User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
string
3..32
characters
The new User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"username": "example_user",
"email": "person@place.com",
"restricted": true
}' \
linode-cli users create \
\
Response Samples
200
default
{
"email" : "example_user@linode.com" ,
"restricted" : true ,
"ssh_keys" : [
"home-pc" ,
"laptop"
],
"tfa_enabled" : null ,
"username" : "example_user"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
New User created successfully.
string <email>
The email address for this User, for account management communications, and may be used for other communications as configured.
boolean
If true, this User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
array of strings
A list of SSH Key labels added by this User. These are the keys that will be deployed if this User is included in the authorized_users field of a
create Linode ,
rebuild Linode , or
create Disk request.
boolean
A boolean value indicating if the User has Two Factor Authentication (TFA) enabled. See the Create Two Factor Secret (
/profile/tfa-enable ) endpoint to enable TFA.
string
3..32
characters
This User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User Delete DELETE
https://api.linode.com/v4/account/users/{username}
Deletes a User. The deleted User will be immediately logged out and may no longer log in or perform any actions. All of the User’s Grants will be removed.
Authorizations personalAccessToken oauth account:read_write
Path Parameters username string
Required The username to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
\
linode-cli users delete example_user
Response Samples
200
default
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
User deleted successfully.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User View GET
https://api.linode.com/v4/account/users/{username}
Returns information about a single User on your Account.
Authorizations personalAccessToken oauth account:read_only
Path Parameters username string
Required The username to look up.
Request Samples
Shell
CLI
curl -H "Authorization: Bearer $TOKEN " \
linode-cli users view example_user
Response Samples
200
default
{
"email" : "example_user@linode.com" ,
"restricted" : true ,
"ssh_keys" : [
"home-pc" ,
"laptop"
],
"tfa_enabled" : null ,
"username" : "example_user"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
The requested User object
string <email>
The email address for this User, for account management communications, and may be used for other communications as configured.
boolean
If true, this User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
array of strings
A list of SSH Key labels added by this User. These are the keys that will be deployed if this User is included in the authorized_users field of a
create Linode ,
rebuild Linode , or
create Disk request.
boolean
A boolean value indicating if the User has Two Factor Authentication (TFA) enabled. See the Create Two Factor Secret (
/profile/tfa-enable ) endpoint to enable TFA.
string
3..32
characters
This User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User Update PUT
https://api.linode.com/v4/account/users/{username}
Update information about a User on your Account. This can be used to change the restricted status of a User. When making a User restricted, no grants will be configured by default and you must then set up grants in order for the User to access anything on the Account.
Authorizations personalAccessToken oauth account:read_write
Path Parameters username string
Required The username to look up.
Request Body Schema boolean
If true, this User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
array of strings
A list of SSH Key labels added by this User. These are the keys that will be deployed if this User is included in the authorized_users field of a
create Linode ,
rebuild Linode , or
create Disk request.
string
3..32
characters
This User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
Request Samples
Shell
CLI
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"username": example_user
"restricted": true
}' \
linode-cli users update example_user \
\
true
Response Samples
200
default
{
"email" : "example_user@linode.com" ,
"restricted" : true ,
"ssh_keys" : [
"home-pc" ,
"laptop"
],
"tfa_enabled" : null ,
"username" : "example_user"
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
User updated successfully.
string <email>
The email address for this User, for account management communications, and may be used for other communications as configured.
boolean
If true, this User must be granted access to perform actions or access entities on this Account. See
/account/users/{username}/grants for details on how to configure grants for a restricted User.
array of strings
A list of SSH Key labels added by this User. These are the keys that will be deployed if this User is included in the authorized_users field of a
create Linode ,
rebuild Linode , or
create Disk request.
boolean
A boolean value indicating if the User has Two Factor Authentication (TFA) enabled. See the Create Two Factor Secret (
/profile/tfa-enable ) endpoint to enable TFA.
string
3..32
characters
This User’s username. This is used for logging in, and may also be displayed alongside actions the User performs (for example, in Events or public StackScripts).
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User's Grants View GET
https://api.linode.com/v4/account/users/{username}/grants
Returns the full grants structure for the specified account User (other than the account owner, see below for details). This includes all entities on the Account alongside the level of access this User has to each of them.
The current authenticated User, including the account owner, may view their own grants at the
/profile/grants endpoint, but will not see entities that they do not have access to.
Authorizations personalAccessToken oauth account:read_only
Path Parameters username string
Required The username to look up.
Request Samples
Shell
curl -H "Authorization: Bearer $TOKEN " \
Response Samples
200
204
default
{
"domain" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"global" : {
"account_access" : "read_only" ,
"add_domains" : true ,
"add_images" : true ,
"add_linodes" : true ,
"add_longview" : true ,
"add_nodebalancers" : true ,
"add_stackscripts" : true ,
"add_volumes" : true ,
"cancel_account" : false ,
"longview_subscription" : true
},
"image" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"linode" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"longview" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"nodebalancer" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"stackscript" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"volume" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
]
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
204
default
The User's grants.
array of objects
The grants this User has pertaining to Domains on this Account. There will be one entry per Domain on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
object
A structure containing the Account-level grants a User has.
stringEnum:
read_only
read_write
The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users.
boolean
If true, this User may add Domains.
boolean
If true, this User may add Images.
boolean
If true, this User may create Linodes.
boolean
If true, this User may create Longview clients and view the current plan.
boolean
If true, this User may add NodeBalancers.
boolean
If true, this User may add StackScripts.
boolean
If true, this User may add Volumes.
boolean
If true, this User may cancel the entire Account.
boolean
If true, this User may manage the Account’s Longview subscription.
array of objects
The grants this User has pertaining to Images on this Account. There will be one entry per Image on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Linodes on this Account. There will be one entry per Linode on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Longview Clients on this Account. There will be one entry per Longview Client on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to NodeBalancers on this Account. There will be one entry per NodeBalancer on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to StackScripts on this Account. There will be one entry per StackScript on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Volumes on this Account. There will be one entry per Volume on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
This is an unrestricted User, and therefore has no grants to return. This User may access everything on the Account and perform all actions.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
User's Grants Update PUT
https://api.linode.com/v4/account/users/{username}/grants
Update the grants a User has. This can be used to give a User access to new entities or actions, or take access away. You do not need to include the grant for every entity on the Account in this request; any that are not included will remain unchanged.
Authorizations personalAccessToken oauth account:read_write
Path Parameters username string
Required The username to look up.
Request Body Schema array of objects
The grants this User has pertaining to Domains on this Account. There will be one entry per Domain on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
object
A structure containing the Account-level grants a User has.
stringEnum:
read_only
read_write
The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users.
boolean
If true, this User may add Domains.
boolean
If true, this User may add Images.
boolean
If true, this User may create Linodes.
boolean
If true, this User may create Longview clients and view the current plan.
boolean
If true, this User may add NodeBalancers.
boolean
If true, this User may add StackScripts.
boolean
If true, this User may add Volumes.
boolean
If true, this User may cancel the entire Account.
boolean
If true, this User may manage the Account’s Longview subscription.
array of objects
The grants this User has pertaining to Images on this Account. There will be one entry per Image on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Linodes on this Account. There will be one entry per Linode on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Longview Clients on this Account. There will be one entry per Longview Client on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to NodeBalancers on this Account. There will be one entry per NodeBalancer on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to StackScripts on this Account. There will be one entry per StackScript on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Volumes on this Account. There will be one entry per Volume on the Account.
integer
The ID of the entity this grant applies to.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
Request Samples
Shell
curl -H "Content-Type: application/json" \
"Authorization: Bearer $TOKEN " \
'{
"global": {
"add_linodes": true,
"add_nodebalancers": false,
"add_domains": true,
"add_longview": false,
"add_stackscripts": true,
"longview_subscription": true,
"add_images": true,
"add_volumes": true,
"account_access": "read_only",
"cancel_account": false
},
"domain": [
{
"id": 123,
"permissions": "read_only"
}
],
"image": [
{
"id": 123,
"permissions": "read_only"
}
],
"linode": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 234,
"permissions": "read_write"
},
{
"id": 345,
"permissions": "read_only"
},
],
"longview": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 234,
"permissions": "read_write"
}
],
"nodebalancer": [
{
"id": 123,
"permissions": "read_write"
}
],
"stackscript": [
{
"id": 123,
"permissions": "read_only"
},
{
"id": 124,
"permissions": "read_write"
}
],
"volume": [
{
"id": 123,
"permissions": "read_only"
}
]
}' \
Response Samples
200
default
{
"domain" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"global" : {
"account_access" : "read_only" ,
"add_domains" : true ,
"add_images" : true ,
"add_linodes" : true ,
"add_longview" : true ,
"add_nodebalancers" : true ,
"add_stackscripts" : true ,
"add_volumes" : true ,
"cancel_account" : false ,
"longview_subscription" : true
},
"image" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"linode" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"longview" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"nodebalancer" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"stackscript" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
],
"volume" : [
{
"id" : 123 ,
"label" : "example-entity" ,
"permissions" : "read_only"
}
]
}
{
"errors" : [
{
"field" : "fieldname" ,
"reason" : "fieldname must be a valid value"
}
]
}
Responses
200
default
Grants updated successfully.
array of objects
The grants this User has pertaining to Domains on this Account. There will be one entry per Domain on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
object
A structure containing the Account-level grants a User has.
stringEnum:
read_only
read_write
The level of access this User has to Account-level actions, like billing information. A restricted User will never be able to manage users.
boolean
If true, this User may add Domains.
boolean
If true, this User may add Images.
boolean
If true, this User may create Linodes.
boolean
If true, this User may create Longview clients and view the current plan.
boolean
If true, this User may add NodeBalancers.
boolean
If true, this User may add StackScripts.
boolean
If true, this User may add Volumes.
boolean
If true, this User may cancel the entire Account.
boolean
If true, this User may manage the Account’s Longview subscription.
array of objects
The grants this User has pertaining to Images on this Account. There will be one entry per Image on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Linodes on this Account. There will be one entry per Linode on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Longview Clients on this Account. There will be one entry per Longview Client on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to NodeBalancers on this Account. There will be one entry per NodeBalancer on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to StackScripts on this Account. There will be one entry per StackScript on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
array of objects
The grants this User has pertaining to Volumes on this Account. There will be one entry per Volume on the Account.
integer
The ID of the entity this grant applies to.
string
The current label of the entity this grant applies to, for display purposes.
stringEnum:
read_only
read_write
The level of access this User has to this entity. If null, this User has no access.
Error
array of objects
string
The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as “null” if the error is not specific to any single element of the request.
string
What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to
open a Support Ticket or perform some other action before you can complete the request successfully.
